CLI reference¶

Every subcommand of the stellar executable, with every flag, exit code, and at least three example invocations (including the failure modes).

Synopsis¶

stellar <command> [options]

Commands:
  init <slug>      Scaffold a new project (writes stellar.yaml + dirs)
  ingest           Build LanceDB + DuckDB stores from raw inputs
  serve            Run uvicorn against the configured project
  build-frontend   Build the React SPA with project branding
  deploy           rsync to the configured deploy target + emit nginx/systemd
  doctor           Validate stellar.yaml against the data directory

Common options:
  --config PATH    Path to stellar.yaml (default: ./stellar.yaml)
  --version        Print version and exit
  -h, --help       Show this help

Global exit codes¶

Code	Meaning
0	Success
1	Command-specific failure (e.g. `doctor` found errors)
2	Usage error — missing config, unknown command, bad flag

`stellar init <slug>`¶

Scaffold a new project directory. Writes a minimal stellar.yaml, a data/raw/ subdirectory, a README.md, and a .gitignore that hides the generated data stores.

Flags¶

Flag	Description
`slug`	Positional. Used in URLs, directory names, and `project.slug`.
`--dir`	Where to create the project. Default `./<slug>`.

Exit codes¶

Code	When
0	Scaffold complete.
2	Target directory exists and is non-empty.

Examples¶

# Scaffold ./my_atlas
stellar init my_atlas

# Scaffold into a specific path
stellar init my_atlas --dir /srv/atlases/my_atlas

# Refuses to overwrite a non-empty directory
mkdir already_here && touch already_here/file
stellar init already_here
# stellar: /abs/path/already_here exists and is not empty — refusing to overwrite
# exit 2

`stellar ingest`¶

Reads the h5ad / Seurat .rds inputs declared in stellar.yaml and builds the gene-major Lance store, the DuckDB metadata file, and every enabled module's parquet output. Idempotent — re-running drops and recreates the artifacts.

Flags¶

Flag	Description
`--config`	Path to `stellar.yaml` (default `./stellar.yaml`).
`--quiet`	Suppress per-step progress lines.

Exit codes¶

Code	When
0	All stores built.
1	A module's `ingest()` raised (validation error).
2	`--config` path doesn't exist.

Examples¶

# Default: stellar.yaml in the current directory
stellar ingest

# Explicit config path
stellar ingest --config examples/pbmc_3k/stellar.yaml

# Quiet mode — only the final "ingest complete" line
stellar ingest --quiet

# Missing config → exit 2
stellar ingest --config /tmp/nope.yaml
# stellar ingest: no config at /tmp/nope.yaml
# exit 2

The first ingest of a Seurat .rds input triggers an R subprocess conversion. See Recipes → From a Seurat object for the prerequisites.

`stellar serve`¶

Run uvicorn against the project's FastAPI app. Mounts the always-on core routes (/api/config, /api/embedding/coords, …) and one router per enabled module under /api/<module>/.... Also mounts the pre-built SPA at project.base_url.

Flags¶

Flag	Description
`--config`	Path to `stellar.yaml` (default `./stellar.yaml`).
`--host`	Bind host. Default `127.0.0.1` (localhost only).
`--port`	Bind port. Default `18901`.
`--reload`	Dev-mode auto-reload — watches `stellar/`.

Exit codes¶

Code	When
0	Process exits cleanly (SIGINT/SIGTERM).
2	`--config` path doesn't exist.

Examples¶

# Localhost-only on the default port
stellar serve --config stellar.yaml

# Public binding — combine with a reverse proxy
stellar serve --host 0.0.0.0 --port 8000

# Hot-reload during development
stellar serve --reload

# Missing config → exit 2
stellar serve --config nope.yaml
# stellar serve: no config at /abs/path/nope.yaml
# exit 2

For production, run stellar serve under a systemd unit and put nginx in front of it. See Deploy for the full recipe.

`stellar build-frontend`¶

Run the SPA build (npm install + vite build) against project.base_url so all asset URLs share that prefix. Writes the bundle to stellar/frontend/dist/ inside the installed package — the next stellar serve picks it up automatically.

You only need to run this if you're changing base_url, customising the SPA source, or installing from a clone (the wheel ships a pre-built bundle).

Flags¶

Flag	Description
`--config`	Path to `stellar.yaml` (default `./stellar.yaml`).
`--skip-install`	Skip `npm install` (use if you already ran it).

Exit codes¶

Code	When
0	Bundle built.
1	`npm install` or `npm run build` returned non-zero.
2	`--config` missing, `package.json` missing, or `npm` not on PATH.

Examples¶

# Standard build
stellar build-frontend --config stellar.yaml

# Skip the install step on a repeat build
stellar build-frontend --skip-install

# Failure mode: no Node on PATH
stellar build-frontend
# stellar build-frontend: `npm` not on PATH — install Node 18+ first.
# exit 2

`stellar deploy`¶

Rsync the SPA bundle (and any pre-baked static artifacts under data/static/) to the configured deploy.target_dir, then print the matching nginx + systemd snippets the maintainer can paste.

Flags¶

Flag	Description
`--config`	Path to `stellar.yaml` (default `./stellar.yaml`).
`--target`	Override `deploy.target_dir` from `stellar.yaml`.
`--dry-run`	Show what rsync would copy without writing.

Exit codes¶

Code	When
0	Rsync succeeded; snippets printed.
2	Pre-check failed: missing config, no built SPA, missing `rsync`, or no `--target` and no `deploy.target_dir`.
N	Rsync's own exit code on a real failure (network, permissions, …).

Examples¶

# Target read from stellar.yaml's deploy.target_dir
stellar deploy --config stellar.yaml

# Override the target on the command line
stellar deploy --config stellar.yaml --target /var/www/html/my_atlas

# Dry-run — see what would be copied
stellar deploy --dry-run

# Failure: no SPA bundle yet
stellar deploy
# stellar deploy: no built SPA — run `stellar build-frontend` first.
# exit 2

`stellar doctor`¶

Validate the project against its stellar.yaml. Catches the failure modes that produce confusing runtime errors:

Input h5ad / .rds missing or unreadable
Cohort column names that don't exist in obs
UMAP not at the configured obsm_key (or fallback obs columns)
Module source_dir missing required parquet files
DuckDB / Lance artifacts older than the source h5ad (= stale build)

Output is plain text grouped by severity (ERROR / WARN / INFO).

Flags¶

Flag	Description
`--config`	Path to `stellar.yaml` (default `./stellar.yaml`).

Exit codes¶

Code	When
0	No errors. (Warnings are still exit-0; you may want to fix them.)
1	At least one error.
2	`--config` path doesn't exist.

Examples¶

# Clean project — exit 0
stellar doctor
# stellar doctor: 0 issues — your project is healthy.

# Project with a misnamed cohort column — exit 1
stellar doctor
#   ✗ [input.matrices.primary] cohort.cell_type_column='cell_type' not in obs;
#     available cols: ['CellType', 'donor', 'condition']…
#
# stellar doctor: 1 errors · 0 warnings
# exit 1

# Use in CI: gate deploy on a clean atlas
stellar doctor --config stellar.yaml && stellar deploy --config stellar.yaml

Common workflows¶

First-time setup¶

stellar init my_atlas
cd my_atlas
# drop your h5ad into data/raw/, edit stellar.yaml
stellar doctor
stellar ingest
stellar serve

After editing inputs or config¶

stellar doctor   # catches any new mismatches
stellar ingest   # rebuilds stores
# the running `stellar serve` doesn't auto-reload the stores; restart it

Production rollout¶

# On the build host
stellar doctor --config stellar.yaml         # exit 0 required
stellar ingest --config stellar.yaml
stellar build-frontend --config stellar.yaml  # only if base_url changed
stellar deploy --config stellar.yaml         # rsync + snippet
# Then on the web host, restart the systemd unit:
sudo systemctl restart stellar-<slug>.service

See Deploy for the nginx + systemd templates.

CLI reference¶

Synopsis¶

Global exit codes¶

stellar init <slug>¶

Flags¶

Exit codes¶

Examples¶

stellar ingest¶

Flags¶

Exit codes¶

Examples¶

stellar serve¶

Flags¶

Exit codes¶

Examples¶

stellar build-frontend¶

Flags¶

Exit codes¶

Examples¶

stellar deploy¶

Flags¶

Exit codes¶

Examples¶

stellar doctor¶

Flags¶

Exit codes¶

Examples¶

Common workflows¶

First-time setup¶

After editing inputs or config¶

Production rollout¶

`stellar init <slug>`¶

`stellar ingest`¶

`stellar serve`¶

`stellar build-frontend`¶

`stellar deploy`¶

`stellar doctor`¶