CLI reference

This page lists the supported ndea commands, flags, and release channels.

Walkthroughs live in Getting started. Dev-side commands (vp run dev, vp run gen, …) live in Contributing.

Synopsis

ndea [paths...]                                  # default; equivalent to `ndea view`
ndea view [paths...] [options]
ndea update [options]
ndea gc [options]
ndea doctor [--check-network] [--strict]
ndea completions <bash|zsh|fish>
ndea complete -- <args...>                       # internal; called by completion scripts
ndea --help | --version

Shorthand

ndea path/to/data.zarr is equivalent to ndea view path/to/data.zarr.

`ndea view`

Open one or more Zarr stores, or a YAML project config, in ndea.

Arguments

Name	Type	Description
`paths…`	one or more paths	Zarr stores or a single YAML project config

A single .yaml / .yml path is parsed as a multi-dataset project config (see Project YAML).

Options

Option	Type	Default	Description
`--port <port>`	integer	`5055`	TCP port for the local server
`--host <host>`	string	`127.0.0.1`	Hostname to bind
`--no-open`	boolean	`false`	Do not auto-open the browser
`--no-static`	boolean	`false`	Do not serve the bundled frontend (Vite serves it in dev mode)
`--obs-columns <list>`	string	all columns	Comma-separated subset of obs columns to load
`--preset <name>`	string	`annotate`	Shipped preset; currently only `annotate`

--port accepts integers in [1, 65535].

`ndea update`

Download and activate the latest release for a channel. ndea verifies the SHA-256 checksum before switching versions.

Not available on Windows. Windows installs are a single ndea.exe with no versions tree and no symlink to swap, so the command exits with an error; re-run install.ps1 to move to a newer release.

Options

Option	Type	Default	Description
`--channel <channel>`	`stable` \| `latest` \| `pre-release`	`stable`	Release channel to resolve
`--force`	boolean	`false`	Re-install even when already on the target
`--no-gc`	boolean	`false`	Skip the post-update auto-gc that removes inactive versions

For standalone installs, a successful update keeps only the active version by default. Pass --no-gc to retain inactive versions, then prune them later with ndea gc.

For mise-managed installs, ndea update updates the active mise config through mise and does not write to ~/.ndea/versions. --no-gc has no effect because mise owns version retention.

A running ndea view session continues using the version it started with.

To install a specific older standalone release, uninstall the current standalone installation, then pass its tag to the installer:

rm -f "$HOME/.local/bin/ndea"
rm -rf "$HOME/.ndea"
curl -fsSL https://czbiohub-sf.github.io/nd-embedding-atlas/install.sh | sh -s -- v0.1.0

On Windows, pass the tag to the installer; it replaces ndea.exe in place, so no removal step is needed:

& ([scriptblock]::Create((irm https://czbiohub-sf.github.io/nd-embedding-atlas/install.ps1))) -Version v0.1.0

For mise-managed installs, select a version explicitly:

mise use -g --pin github:czbiohub-sf/nd-embedding-atlas@0.1.0

`ndea gc`

Prune old installed versions. ndea always preserves the active version.

Options

Option	Type	Default	Description
`--keep <N>`	integer	`1`	Number of versions to keep (active counts; min 1)

`ndea doctor`

Diagnose the install. Prints binary path, symlink integrity, active version, installed versions with disk usage. Exit code 0 if healthy, 1 on hard anomalies (broken symlink, missing active binary).

On Windows the symlink and installed-versions sections are omitted, because that layout has neither. Everything else, including the extracted-library cache check, reports normally.

Options

Option	Type	Default	Description
`--check-network`	boolean	`false`	Probe GitHub Releases API reachability over the network (3 s timeout)
`--strict`	boolean	`false`	Treat warnings as errors (non-zero exit)

`ndea completions`

Emit shell completion scripts.

Arguments

Name	Type	Description
shell	`bash` \| `zsh` \| `fish`	Shell to emit for

Usage

# bash / zsh: load on demand
source <(ndea completions bash)
source <(ndea completions zsh)

# fish: drop into the completions dir
ndea completions fish > ~/.config/fish/completions/ndea.fish

view's positional completion filters to *.zarr directories and *.yaml / *.yml files.

Release channels

Channel	Resolves to	Cadence
`stable`	latest semver-tagged release (e.g. `v0.1.0`)	Manual; cut from `main` when ready
`latest`	alias for `stable`	Same as `stable`
`pre-release`	newest published alpha / beta / rc release	Manual; unavailable until a pre-release has been published

stable and latest use GitHub's latest release. pre-release selects the newest published, non-draft semver pre-release. ndea update resolves the channel through the public GitHub Releases API at update time.

State directory layout

~/.ndea/:

~/.ndea/
  current-version              # Plain text: "<tag>\n<sha256>\n"
  versions/
    v0.1.0/
      ndea                     # bun-compiled binary (~185 MB, embeds libduckdb)
    v0.1.1/
      …
  locks/
    install.lock               # PID file backing the install/update mutex
~/.cache/ndea/
  0.1.0/
    libduckdb.{dylib,so}       # Extracted from the binary on first launch

A compiled version takes about 185 MB. ndea gc also removes version-scoped native-library caches corresponding to pruned releases.

~/.local/bin/ndea points to the active binary under ~/.ndea/versions/<tag>/ndea.

On Windows the layout is flat, with no versions tree and no symlink:

%LOCALAPPDATA%\ndea\
  bin\
    ndea.exe                   # On PATH via a user environment entry
  0.1.0\
    duckdb.dll                 # Extracted from the binary on first launch
%USERPROFILE%\.ndea\
  current-version              # Plain text: "<tag>\n<sha256>"

DuckDB ships the Windows library as duckdb.dll rather than libduckdb.dll. Because only one version is ever installed, ndea gc has nothing to prune.

Exit codes

Code	Meaning
`0`	Success
`1`	General error (missing argument, fatal startup, lock contention, …)
`130`	Interrupted (`Ctrl-C` during a long-running command)

CLI reference

On this page