Install¶

To get started on a lightcone project, you need three things on your machine: Python 3.11+, the lightcone command line tool lc, and an agent-based CLI (currently supporting Claude Code).
A container runtime is optional but recommended.

1. Python¶

If you don't already have a recent Python

brew install python@3.12

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

module load python      # NERSC Python (3.11+)

conda create -n your-env-name python=3.11 -y
conda activate your-env-name

conda deactivate
mv ~/.conda/envs/your-env-name $SCRATCH/conda-envs/
ln -s $SCRATCH/conda-envs/your-env-name ~/.conda/envs/your-env-name

curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12

2. lightcone-cli¶

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

uv tool install lightcone-cli

python -m pip install lightcone-cli

uv tool install lightcone-cli

# NERSC python module
module load python
python -m pip install --user lightcone-cli   # lands in ~/.local/bin/

# Conda env
conda activate your-env-name
python -m pip install lightcone-cli

git clone https://github.com/LightconeResearch/lightcone-cli.git
uv pip install -e ./lightcone-cli

git clone https://github.com/LightconeResearch/ASTRA.git
uv pip install -e ./ASTRA

Get a confirmation of the proper installation by running

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

Note Some people may have already set a personal shell alias lc='ls --color'. If that's you, installing lightcone-cli will shadow the alias — make sure to rebind it (e.g. alias l='ls --color').

3. Global configuration¶

~/.lightcone/config.yaml is created automatically the first time you run any lc command. No manual setup step is needed. The file starts as:

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). Feel free to pin the runtime later by editing this file directly.

4. Agentic CLI¶

Most of your interactions with a lightcone project happen through an agent-based CLI. Any agent that can drive a project shell works — the choice is yours.

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

claude --version
claude        # first run prompts for login (claude.ai or API key)

curl -fsSL https://opencode.ai/install | bash

Open a project in your terminal or editor (see Getting Started) and run your agent CLI from inside it. Inside Claude Code you'll type slash commands like /lc-new, /lc-from-code, and /lc-from-paper — see The Agentic 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.

The auto mode picks whichever container runtime 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).

Updating¶

uv tool upgrade lightcone-cli

pip install -U lightcone-cli astra-tools

cd path/to/lightcone-cli
git pull
uv pip install -e .        # only needed if pyproject.toml changed

Uninstalling¶

uv tool uninstall lightcone-cli

pip uninstall lightcone-cli