Command-line interface

The ninja command is the primary way to run cabs and recipes. It takes global options followed by a subcommand:

$ ninja [--config FILE] [--backend NAME] COMMAND ...

Global options

--config FILE

Path to a config file (default: ~/.shinobi/config.yml). See Configuration.

--backend NAME

Override the default backend for this invocation.

Targets

Commands that act on a cab or recipe take a target of the form path/to/file.py:name or dotted.module.path:name. The name must resolve to a Cab, Recipe, or a @shinobi.step-decorated function.

ninja run – run a target

Runs a Cab, Recipe, or step. The target’s own parameters become the command’s options – run ninja run TARGET --help to see them.

$ ninja run myrecipe.py:image --ms data.ms --prefix out
$ ninja run myrecipe.py:selfcal --ms data.ms

Add --dryrun to render the execution graph without running anything:

$ ninja run myrecipe.py:selfcal --ms data.ms --dryrun
[ image ]
    |
    v
[ mask ]

The dry run executes the recipe’s real Python control flow with every cab swapped for a no-op that records the call, so it shows the one path taken for the given inputs – never an untaken branch.

Add --cache-dir DIR / --no-cache to control step-level result caching (a step must also opt in via its own Scope.cache, an enclosing recipe’s, or AppConfig.cache.enabled – these flags alone don’t turn caching on):

$ ninja run myrecipe.py:selfcal --ms data.ms --cache-dir /scratch/cache
$ ninja run myrecipe.py:selfcal --ms data.ms --no-cache

By default, running cabs’ stdout/stderr are echoed live as they run (native/container backends only). Add --quiet to restore the old behavior of a silent run followed by one dump of captured output at the end; this overrides AppConfig.log.stream for the invocation.

Add --remote user@host:/path to launch on a remote host instead of locally: the target file and its statically-discoverable cab deps are synced over, then the run happens detached – check progress with ninja status. --add-venv/--no-add-venv (default: on) sources venv/bin/activate or .venv/bin/activate under the remote path first, if present. --include PATH (repeatable) syncs extra files/dirs alongside the target, for orchestration code the static cab-dep scan can’t see:

$ ninja run myrecipe.py:selfcal --ms data.ms --remote user@cluster:/scratch/run1
$ ninja run myrecipe.py:selfcal --ms data.ms --remote user@cluster:/scratch/run1 --include extra_cabs.yml

ninja cab – inspect a cab schema by file

Dumps a cab’s resolved schema (as loaded from a cult-cargo style YAML file) as JSON:

$ ninja cab cabs.yml wsclean

ninja cabs – look up installed cabs by name

Looks up cabs by name across installed shinobi.cabs providers (e.g. dosho), instead of pointing at a specific YAML file:

$ ninja cabs list
$ ninja cabs show wsclean

ninja download – fetch cab definitions

Downloads cab definitions for use with the file-based ninja cab / cult-cargo loader. --cult-cargo downloads cab definitions from GitHub; --dest-dir sets the destination (default: .shinobi/cabs/cultcargo); --version picks latest (highest v* tag), a tag, a branch, or a commit SHA:

$ ninja download --cult-cargo
$ ninja download --cult-cargo --version v1.2.3 --dest-dir .shinobi/cabs/cultcargo

ninja compile – offload a recipe

Compiles a purely-declarative recipe into a cluster workflow and, with --submit, hands it off and detaches. See Offloading to a cluster.

$ ninja compile myrecipe.py:pipe --target /scratch/made.ms --container-runtime none
$ ninja compile myrecipe.py:pipe --target /scratch/made.ms --submit

Options: --engine (workflow engine, slurm in v1), --workdir (working directory for compiled jobs), --container-runtime (runtime to wrap imaged cabs in; none for bare argv), and --submit (submit and detach).

ninja status – check a detached run

Reports a detached offloaded run’s progress from the handle file written by ninja compile --submit or ninja run --remote, querying the engine fresh (no persistent process):

$ ninja status /scratch/.shinobi/pipe/handle.json

ninja version – print the version

$ ninja version