Install¶

You need three things on your machine: Python 3.11+, the lc CLI, and Claude Code. A container runtime is optional but recommended.

1. Python 3.11+¶

If you don't already have a recent Python:

macOS: brew install python@3.12
Linux: your package manager (apt install python3.12, etc.) or pyenv.
Windows: python.org or WSL.

Confirm:

python3 --version           # → Python 3.11.x or newer

2. lightcone-cli¶

The published name on PyPI is lightcone-cli; the command it provides is lc.

pip install lightcone-cli

If you use uv (recommended):

uv pip install lightcone-cli
# or, project-local:
uv tool install lightcone-cli

Confirm:

lc --version                # → lightcone-cli, version ...

Heads-up about the lc name. lc is not a standard Unix tool, but a few people have a personal shell alias lc='ls --color'. If that's you, installing lightcone-cli will shadow the alias — rebind it (e.g. alias l='ls --color').

3. One-time setup¶

lc setup

This creates ~/.lightcone/config.yaml with:

container:
  runtime: auto

auto detects whichever of podman, docker, or podman-hpc is on your PATH (and skips docker if its daemon isn't running). You can pin the runtime later by editing this file.

4. Claude Code¶

Most of your interactions with lightcone-cli happen through Claude Code, the CLI that drives Claude.

curl -fsSL https://claude.ai/install.sh | bash

Open a project (in the next page we make one) with:

claude

Inside Claude Code you'll type slash commands like /lc-new and /lc-build — see The Claude Code Workflow.

5. (Optional) Docker or Podman¶

If your analysis declares a container: (which it usually should — it makes the result reproducible across machines), you need a container runtime:

Local laptop: install Podman (rootless, no daemon) or Docker.
HPC login node: see Running on a Cluster.

lc setup's auto mode picks whichever you have. If you don't have either, you can still use lc — set runtime: none in ~/.lightcone/config.yaml and recipes will run on the host without isolation.

Sanity check¶

lc --help
lc init --help

Both should print help text. If lc is shadowed by an ls alias, unset it (unalias lc) or use the full path ($(which lc) --version).