cli-reference

name	cli-reference
description	Documents the human-facing cindra and cindra-gui command-line interfaces. Covers every command and option with its short form, long form, type, default, and effect, the MCP tool each command maps to, its failure modes, and how the CLI path diverges from the MCP path. Use when a user asks what a cindra or cindra-gui command or option does, or when the MCP server is unavailable and the user must be told what to run by hand.
user-invocable	true

CLI reference

The cindra and cindra-gui CLIs are HUMAN-FACING tools. You MUST never invoke them. Print the command, ask the user to run it, and ask them to paste the output back.

The one exemption is --help. cindra --help, cindra COMMAND --help, cindra-gui --help, and cindra-gui COMMAND --help may be run, and no other invocation is exempt. /cindra-mcp-environment-setup owns that exemption along with the cindra omp recovery command it drives.

---

Scope

Covers:

• The complete cindra and cindra-gui command surface, each command's purpose, and its MCP equivalent
• Every declared option: short form, long form, type, default, required or flag status, and effect
• Per-command failure modes and how the error routing guard renders them
• How cindra run diverges from an MCP batch, and how a hand-launched viewer diverges from launch_viewer_tool
• What to tell a user to run when the MCP server cannot be restored in this session

Does not cover:

• The MCP batch workflow, prerequisite validation, and resource sizing (see /single-recording-processing, /multi-recording-processing)
• Configuration parameter meanings and tuning guidance (see /single-recording-configuration, /multi-recording-configuration)
• Output data formats the commands produce (see /single-recording-results, /multi-recording-results)
• Viewer controls, display state, and the classifier panel (see /visualization)
• Diagnosing why the MCP server is down, and the cindra omp linking workflow (see /cindra-mcp-environment-setup)
• Raw data preparation and acquisition parameter files (see /acquisition-data-preparation)

Handoff rules: If the user wants an operation performed rather than explained, use the MCP tools and invoke the owning skill. If the MCP tools are unavailable, invoke /cindra-mcp-environment-setup first, and fall back to the handoff table below only after the server cannot be restored.

---

Agent requirements

You MUST answer CLI questions from this skill or from cindra COMMAND --help, never from memory. When a user's report disagrees with this reference, ask them to run cindra COMMAND --help and read the installed build's answer.

---

Command surface

Two entry points ship from pyproject.toml. cindra maps to cindra.interface.cli:cindra_cli and cindra-gui maps to cindra.interface.gui_cli:cindra_gui. The GUI entry point is separate so that a headless pipeline run never loads Qt.

Command	Kind	Purpose	MCP equivalent
cindra	group	Entry point. Dispatches to the subcommands	None, dispatch only
cindra mcp	command	Starts the data processing MCP server	None, it hosts the server
cindra omp	command	Reports and links the macOS OpenMP runtime Numba loads	None, and the command errors off macOS
cindra configure	command	Generates a default pipeline configuration file	generate_config_file_tool
cindra run	command	Runs a pipeline from a configuration file	execute_full_pipeline_tool, execute_processing_jobs_tool
cindra-gui	group	Entry point. Dispatches to the viewer subcommands	None, dispatch only
cindra-gui roi	command	Launches the ROI viewer	launch_viewer_tool(viewer_type="roi")
cindra-gui registration	command	Launches the registration quality viewer	launch_viewer_tool(viewer_type="registration")
cindra-gui tracking	command	Launches the multi-recording tracking viewer	launch_viewer_tool(viewer_type="tracking")
cindra-gui mcp	command	Starts the GUI MCP server	None, it hosts the server

cindra omp is the only command carrying no MCP substitute for its main effect, and it is also the only command confined to one platform. It runs on macOS alone and errors on every other host, so it reports nothing about the TBB runtime a Linux or Windows host needs. check_threading_runtime_tool is the portable check. It runs everywhere, reports the layer the host's platform selects under required_layer, and names a remedy, so it substitutes for the report half of cindra omp on macOS alone and covers every other host on its own. Creating the macOS link still needs the CLI, because the write target usually requires sudo.

---

Option reference

Both groups set a help width of 120 characters. Neither group declares options of its own.

cindra mcp

Short	Long	Type	Default	Status	Effect
-t	--transport	choice of stdio, sse, streamable-http	stdio	optional	Selects the transport to serve

The stdio transport disables the console, because that transport carries the JSON-RPC stream over stdout and a logged line renders the message it interleaves with unparsable.

cindra omp

Short	Long	Type	Default	Status	Effect
-s	--source	existing file	None	optional	Names the runtime to link, omit to search the host for one
-t	--target	file path	None	optional	Names the link to write, omit to derive the loader default
-f	--force	flag	False	flag	Links even on a host whose runtime already loads
-y	--yes	flag	False	flag	Creates the link, omit to report and change nothing

Without -y the command is a report. /cindra-mcp-environment-setup owns the workflow that drives it.

cindra configure

Short	Long	Type	Default	Status	Effect
-p	--pipeline	choice of single-recording, sd, multi-recording, md	none	required	Selects the pipeline to configure
-od	--output-path	existing directory	none	required	Names the directory to write into
-n	--name	string	None	optional	Names the file, defaulting per pipeline type

Omitting -n writes cindra_sd_conf.yaml for a single-recording pipeline and cindra_md_conf.yaml for a multi-recording one. The name keeps every component it carries and gains the .yaml suffix, so -n mouse5_2024.03.01 writes mouse5_2024.03.01.yaml rather than truncating at the last dot. A .yml name is normalized to .yaml. The MCP equivalent takes the whole file path, name included, as its output_path, and normalizes any suffix other than .yaml through Path.with_suffix('.yaml'), which replaces the component following the last dot. The two paths therefore agree on every name carrying no dot and on every name ending in .yaml or .yml. They diverge on any other name carrying a dot, where the MCP tool writes mouse5_2024.03.yaml for the name the CLI writes in full. Ask a user reproducing an agent's file by hand for a dotless name, or hand them the file_path the MCP tool returned.

cindra run

The pipeline type is detected from the configuration file, so one command serves both pipelines and each pipeline ignores the other's flags. With no phase flag set, every phase of the detected pipeline runs in order. With --job-id set, only the matching job runs and every phase flag is ignored.

Short	Long	Type	Default	Status	Effect
-i	--input-path	file path	none	required	Names the configuration file to run
-bw	--binarize-workers	integer	None	optional	Workers for the binarization stage
-rw	--register-workers	integer	None	optional	Workers for the registration stage
-pw	--process-workers	integer	None	optional	Workers for the processing stage
-dw	--discover-workers	integer	None	optional	Workers for the discovery stage
-ew	--extract-workers	integer	None	optional	Workers for the extraction stage
-np	--no-progress	flag	False	flag	Suppresses the progress bars
-id	--job-id	string	None	optional	Runs only the named job
-b	--binarize	flag	False	flag	Runs the binarization phase
-r	--register	flag	False	flag	Runs the registration phase
-p

Two spellings invite a mistake. The output directory is -s here and -od on cindra configure, and -p is --process here while it is --pipeline on cindra configure. Quote the long form whenever you hand a user one of these.

The five worker options follow the shared sentinel convention. Omitting the option accepts the measured default for that stage, -1 requests every available core, and a positive integer is used exactly. Any other non-positive value is rejected. /single-recording-configuration owns that convention.

A single-recording run needs an output path before it starts. The command applies -dp and -s to the loaded configuration, then aborts with a usage error when file_io.output_path is still None, naming both the field and the --output-path flag. A freshly generated configuration carries None there, and generate_config_file_tool leaves it None as well, so a template the agent produced runs only once the user passes -s <output-root> or sets the field in the file. That output root is the parent of the cindra directory the run writes, which is the same value the MCP tools name output_root. Include -s in every single-recording cindra run command you hand over, and confirm the field is set before omitting it.

cindra-gui roi, cindra-gui registration, and cindra-gui tracking

Short	Long	Type	Default	Status	Effect
-r	--recording-path	existing directory	none	required	Names the pipeline output root to open
-d	--dataset	string	None	optional	Selects the multi-recording dataset
-sf	--state-file	file path	None	optional	Names the file the viewer writes its state into

cindra-gui registration declares no --dataset, so passing it there is a usage error. On roi, supplying --dataset switches the viewer into tracked ROI mode. --recording-path takes the pipeline output root, which is the parent of the recording's cindra directory, and launch_viewer_tool names that same value output_root while passing it through this flag. launch_viewer_tool builds exactly these invocations and always supplies --state-file, which is how the MCP path reads live viewer state.

cindra-gui mcp

Carries the same -t / --transport option, with the same choices and the same stdio default, as cindra mcp.

---

Error routing and failure modes

Every command of both CLIs carries a decorator that reports a failure through the console instead of an interpreter traceback. The message reaches stderr at the ERROR level, and the command still exits zero, so the exit code reports whether Click accepted the invocation rather than whether the work succeeded.

Observed	Exit	Meaning
An ERROR line naming the failure, and no traceback	0	A library error. The message names the cause
Usage: ... followed by Error: ...	2	A rejected option value, whether Click or the command body caught it
Aborted!	1	The user interrupted the command
A report ending in an unresolved status, from cindra omp	1	No OpenMP runtime resolved on this host

Never read a zero exit code as success. A library failure exits zero, so ask the user for the terminal output rather than for the exit status, and read the ERROR line to decide what failed. A Click exception passes through the decorator, so every malformed invocation exits 2 whether Click's own validation or the command body caught it.

A traceback means an outdated build. Every command of both groups carries the decorator, so a user reporting a Python stack dump is running a build from before it landed. Ask them to upgrade rather than interpreting the stack.

The failures a user hits most, and where each belongs:

Message names	Cause	Route to
No configuration file, or a bad pipeline type key	-i points at a missing, malformed, or non-YAML file	/single-recording-configuration
A missing configuration field	A hand-edited file dropped a required key	/single-recording-configuration
No cindra_parameters.json, or an acquisition mismatch	The recording was never prepared	/acquisition-data-preparation
TIFF frames of differing shape	The data directory mixes frame geometries	/acquisition-data-preparation
A plane that must be registered before detection	A phase flag ran a phase out of order	/single-recording-processing
No combined_metadata.npz under a recording	A multi-recording input never finished single-recording	/single-recording-processing
No configuration.yaml under a viewer's output root	The recording was never processed	/single-recording-processing
An OpenMP runtime that cannot be located, on macOS	The threading runtime is not on the loader search path	/cindra-mcp-environment-setup
A lock acquisition that timed out	Another cindra process holds the tracker	See the contention warning below

---

How the CLI diverges from the MCP path

cindra run is not a hand-operated version of the batch engine. It calls the sequential pipeline entry points directly, so the two paths differ in ways that change results rather than only timing. State these before recommending any cindra run command.

Topic	cindra run	The MCP batch
Dispatch	One job at a time, in phase order, inside the CLI's process	Every job in its own process, several at once
A failing job	Unwinds the run, later jobs never start and stay SCHEDULED	Confined to its dependency subtree, other work continues
A killed job	Leaves the job at RUNNING in the tracker permanently	Converged to a terminal state naming the likely cause
Prerequisites	Validated for the target plane or recording alone	Validated against the tracker before any job starts
Completed work	Re-run unconditionally	Skipped, reporting that the phases are already complete
Resource budgets	Per-stage counts, with no session core or memory budget	Session core and memory budgets bound admission
Backend threads	Sized to the whole host	Each worker pinned to one backend thread

Three of these are hazards rather than trade-offs, so warn the user before handing over a command.

cindra run rewrites the file -i names. It writes the resolved progress-bar setting and any -dp, -s, or -rp override back into that file before dispatching. A template run once by hand therefore carries one recording's paths, and the next batch the agent prepares inherits them. Tell the user to point -i at a per-recording copy, never at a template the agent uses.

cindra run rewrites the shared bootstrap other workers read. Invoked without --job-id, it persists the recording's configuration and every plane's runtime data from its own start-of-run snapshot. Run against an output directory a live MCP session is working on, it overwrites results those workers already recorded.

Nothing excludes the two paths from each other. Both lock the same tracker file, and that lock serializes individual writes rather than whole jobs. A hand run against a directory the agent is executing can time out on the lock, or restart a job the engine is already running so that two processes write the same plane. Never start an MCP batch over a directory a user has a run in, and ask the user to wait for a session to drain before running anything.

Two smaller mismatches shape the advice you give. -bw genuinely changes binarization, while the MCP binarization class is fixed and discards workers_per_job, so an agent has never changed it. The CLI's per-stage granularity has no MCP counterpart either, because workers_per_job is one value applied to every non-fixed class.

A hand-launched viewer is untracked. launch_viewer_tool records the process so list_viewers_tool, query_viewer_state_tool, and close_viewer_tool reach it, and a viewer the user starts is reachable by none of them.

---

Fallback: what to tell a user when MCP is unavailable

Blocked MCP tool	Tell the user to run
generate_config_file_tool	cindra configure -p single-recording -od <dir>
prepare_single_recording_batch_tool plus the execute tools	cindra run -i <config> -s <output-root>
prepare_multi_recording_batch_tool plus the execute tools	cindra run -i <config>
check_threading_runtime_tool, on macOS alone	cindra omp
launch_viewer_tool(viewer_type="roi")	cindra-gui roi -r <output-root>
launch_viewer_tool(viewer_type="registration")	cindra-gui registration -r <output-root>
launch_viewer_tool(viewer_type="tracking")	cindra-gui tracking -r <output-root> -d <name>

Every rule the divergence section states applies to these rows. One caveat is new here, that neither CLI reports its results in a machine-readable form, so ask the user to paste the terminal output.

Two rows carry a condition the table cannot hold. The single-recording cindra run row keeps -s because the run aborts without a configured output path, and the multi-recording row omits it because that pipeline reads recording_io.recording_directories and recording_io.dataset_name from the file instead. The cindra omp row holds on macOS alone, so on Linux and Windows tell the user to check the TBB runtime with python -c "import tbb" in the environment cindra runs in, and to install tbb4py when that import fails.

Everything else blocks until the server is back. That covers acquisition parameter generation and validation, recording discovery, dataset name resolution, and configuration reading, validation, and modification. It also covers both planning tools get_pipeline_job_universe_tool and size_pipeline_jobs_tool, every batch status, timing, cancel, reset, and cleanup tool, all output verification and query tools, and live viewer state. Say so plainly rather than improvising a substitute.

---

Related skills

Skill	Relationship
/cindra-pipeline	Context: where each command sits in the end-to-end pipeline
/cindra-mcp-environment-setup	Owns the --help exemption, the cindra omp workflow, and MCP recovery
/single-recording-processing	Owns the MCP batch workflow cindra run substitutes for
/multi-recording-processing	Owns the multi-recording batch workflow and its re-run semantics
/single-recording-configuration	Owns the file cindra configure generates and the worker sentinel convention
/multi-recording-configuration	Owns the multi-recording configuration file and its parameters
/acquisition-data-preparation	Owns the raw data and acquisition parameters a run reads
/visualization	Owns viewer controls and the tracked state a hand-launched viewer forfeits
/single-recording-results	Downstream: the output a completed run writes
/multi-recording-results	Downstream: the output a completed multi-recording run writes

---

Verification checklist

Answering a CLI question, tool-settled (run `cindra COMMAND --help`, the sole sanctioned invocation):
- [ ] Answered from this skill or from `COMMAND --help`, never from memory
- [ ] Quoted the long option form, since `-s`, `-p`, and `-od` differ in meaning between commands

Answering a CLI question, reader-judged:
- [ ] Named the MCP equivalent alongside any command the agent could have run itself
- [ ] Invoked no `cindra` or `cindra-gui` command other than `--help`
- [ ] Treated a reported traceback as an outdated build rather than interpreting the stack

Handing a user a CLI command, reader-judged:
- [ ] Confirmed MCP is genuinely unavailable via `/cindra-mcp-environment-setup` first
- [ ] Printed the command for the user instead of running it
- [ ] Passed `-s <output-root>` on a single-recording `cindra run`, or confirmed `file_io.output_path` is already set
- [ ] Named `check_threading_runtime_tool` rather than `cindra omp` for a threading check off macOS
- [ ] Warned that `cindra run` rewrites the configuration file `-i` names
- [ ] Warned about sequential dispatch and abort-on-first-failure before recommending `cindra run`
- [ ] Confirmed no MCP session holds the tracker for that output directory
- [ ] Asked the user to paste the terminal output, since neither CLI reports machine-readable results
- [ ] Read the pasted output for an ERROR line rather than treating a zero exit code as success