lightcone-cli

lightcone-cli (lc) is the execution layer for ASTRA (Agentic Schema for Transparent Research Analysis). Describe your analysis in an astra.yaml specification and lc takes care of the rest — execution, environments, and provenance.

Quick Start

lightcone-cli only requires you to have uv installed on your environment, and will take care of everything else. See how to install uv here: https://docs.astral.sh/uv/getting-started/installation.

Then to install lightcone-cli:

uv tool install lightcone-cli

Create an ASTRA project and launch the built-in local compute offer; no compute configuration is needed. Configure resource offers for larger local allocations or Slurm:

lc init my-analysis
cd my-analysis
# describe your analysis in astra.yaml, write your scripts,
# declare what they import through normal uv interactions:
uv add numpy
# When you are done with your edits, commit:
git add -A && git commit -m "First analysis"
CLUSTER=$(lc compute launch --cpus 1 --memory 1)
lc compute status "$CLUSTER" --wait
# Generate outputs with full provenance tracking
lc materialize "$CLUSTER"
lc compute down "$CLUSTER"

ASTRA specs are plain, structured YAML — they work well hand-written or drafted with any AI coding assistant.

→ Full getting-started guide

Capabilities

• Multiverse analysis — declare methodological decisions with multiple defensible options; lc materializes your analysis across every universe you define
• Provenance by construction — every output is committed to git together with a content-addressed manifest and a re-runnable run record; git-annex carries the bytes, so results travel with the repository
• Locked, isolated execution — a project's environment is pyproject.toml + uv.lock; recipes run in it under a sandbox (Landlock on Linux, Seatbelt on macOS) that keeps undeclared files out and stray writes contained
• Containers and HPC — declare [tool.lightcone.image] and recipes run in a content-addressed image archived in the repository itself; allocate local or Slurm Dask clusters explicitly with lc compute, then pass the cluster name or full ID to run or materialize
• Publication view — declare a license and lc materialize maintains an RO-Crate of the project and its provenance, ready to archive or deposit

→ Full documentation

License

BSD 3-Clause — see LICENSE for details.