Quick Start
Install the Lightcone CLI, start a project, and give it compute.
Your agent installs and runs the Lightcone CLI
You rarely type lc yourself. Once the Lightcone plugin is installed, your coding
agent offers to install the CLI if it's missing, then sets up the project, runs the analysis and
reads its status through the CLI. This page covers installing it yourself, and what you set up once.
Install the CLI
The CLI installs with uv 0.12 or later (check with uv --version). If
you don't have uv yet, install it:
curl -LsSf https://astral.sh/uv/install.sh | shThen install the CLI, which provides the lc command:
uv tool install lightcone-cliThe install also puts git-annex on your PATH, which projects need. If lc runs but git-annex
doesn't, run uv tool update-shell and open a new shell. Check the install:
lc --versionYou also need git, set up to know who you are. uv manages Python itself, so there is no separate Python install.
uv tool upgrade lightcone-cliAn existing lc alias
If your shell already has an alias such as lc='ls --color', it hides the new command: type lc
shows which one runs. Remove the alias with unalias lc, and from your shell profile.
Container support (optional)
By default, recipes run directly on your machine, in the project's locked environment. A project can
instead run them in a container image, by declaring [tool.lightcone.image] in its pyproject.toml
(see lc build). Only those projects need a container runtime:
install Podman or Docker. There is nothing
to configure: lc uses podman-hpc, podman or docker, whichever it finds first. On NERSC, use
podman-hpc, as in NERSC Perlmutter.
Start a project
lc init my-analysislc init creates the project:
my-analysis/
├── astra.yaml # the analysis specification, empty to start
├── pyproject.toml # the environment: the packages recipes can import…
├── uv.lock # …resolved to exact versions
├── .python-version # the Python version, managed by uv
├── .venv/ # built from the lock; local, never committed
├── data/ # input data, stored by git-annex
├── results/ # outputs, written only by lc
├── universes/
│ └── baseline.yaml # the decision values to run with
├── index.md # the report, in MyST
├── myst.yml # the report's configuration
├── .git/ # a git repository, with git-annex set up
├── .gitattributes # which files git-annex stores
├── .gitignore
└── .datalad/ # the project's DataLad dataset identityIn an existing directory or a fresh clone, lc init fills in only what is missing. From there, the
analysis is described in astra.yaml: your agent writes it with you, as in
Your first analysis.
Configure compute
The CLI runs recipes on clusters it starts from the offers in ~/.lightcone/compute.yaml. Without
that file, it uses your own machine, so there is nothing to set up on a laptop or workstation. To use
part of the machine, its GPUs, or a Slurm cluster, write the file as
Configuring compute explains; HPC clusters
has ready configurations for known systems. Then check what the CLI sees:
lc compute resourcesThe commands
Your agent uses these commands, and so can you, for example to check where an analysis stands:
| Command | What it does |
|---|---|
lc init | Set up a project, or restore a clone's local state |
lc compute | Start, inspect and stop clusters |
lc materialize | Make the outputs on a cluster, and commit each one as it lands |
lc status | Show which outputs are current, and the commit each was made at |
lc run | Run one command on a cluster, in the project environment and sandbox |
lc build | Build a containerized project's image, and commit it |
Core concepts explains the model behind them.