Runtime CLI Reference#

Every conda-ship artifact includes a generated runtime. In this page, RUNTIME stands for the runtime name resolved by cs build from [tool.conda-ship].runtime or --runtime. DELEGATE stands for the executable inside the managed prefix that receives pass-through arguments.

For conda-express, RUNTIME is cx. For an embedded conda-express artifact, the staged runtime is cxz.

Global Options#

-v, --verbose

Increase output detail.

-q, --quiet

Suppress non-essential output.

--path PATH

Use a custom install path instead of the distribution default. This applies to bootstrap, status, shell, uninstall, and pass-through delegate commands. Put it before pass-through commands so conda does not interpret it as one of its own options, for example RUNTIME --path /tmp/demo install numpy.

-h, --help

Show runtime help.

-V, --version

Show the runtime version.

RUNTIME bootstrap#

Install conda into the runtime’s install path.

RUNTIME bootstrap [OPTIONS]

Options:

--force

Remove an existing install path before bootstrapping again.

--bundle DIR

Pre-populate the package cache from a directory containing .conda or .tar.bz2 archives. The directory is treated as a flat package archive bundle, not as a conda channel mirror.

--offline

Disable network access. Packages must be available from the local cache, an explicit --bundle, or an embedded bundle.

Examples:

# Standard network bootstrap from the stamped lockfile
RUNTIME bootstrap

# Re-bootstrap into the default install path
RUNTIME bootstrap --force

# Bootstrap into a custom install path
RUNTIME --path /opt/name bootstrap

# Bootstrap from an external bundle directory
RUNTIME bootstrap --bundle ./packages --offline

For an embedded runtime, conda-ship detects the built-in bundle automatically:

RUNTIMEz bootstrap

An explicit --bundle still takes priority over the embedded bundle. Embedded bundle extraction rejects anything except top-level .conda and .tar.bz2 package archive files.

RUNTIME status#

Show runtime and install details.

RUNTIME [--path PATH] status

The output includes the runtime name, runtime version, install path, configured channels, configured package specs, installed package count, and conda executable path for the managed prefix.

RUNTIME shell#

Start a conda-spawn subshell for an environment.

RUNTIME shell [ENV]

Examples:

RUNTIME shell myenv
exit

This command delegates to conda spawn. It uses the runtime’s default install path.

RUNTIME uninstall#

Remove the install path and named environments.

RUNTIME uninstall [OPTIONS]
-y, --yes

Skip the interactive confirmation prompt.

The command removes the managed install path, including named environments below it, and prints a hint for removing the runtime through the package manager or install method that provided the runtime binary.

RUNTIME help#

Show the runtime help text.

RUNTIME help
Terminal recording of a generated runtime printing its version and runtime-specific activation guidance.

Generated runtimes expose their own command surface before pass-through to the delegate.#

Pass-Through Commands#

Any command not listed above is passed through to the configured delegate executable after bootstrap. For a runtime whose delegate is conda, this looks like:

RUNTIME create -n myenv python=3.12 numpy
RUNTIME install -n myenv pandas
RUNTIME list -n myenv
RUNTIME env list
RUNTIME info

# Use a custom runtime install path for pass-through commands
RUNTIME --path /tmp/name install -n myenv pandas

If the install path does not exist, pass-through commands automatically bootstrap first.

The delegate process receives a conda-like base environment: CONDA_ROOT_PREFIX, CONDA_PREFIX, CONDA_DEFAULT_ENV=base, CONDA_SHLVL=1, and a PATH with the managed prefix’s executable directories first. On Unix this includes bin and condabin; on Windows this includes the root prefix, Library binary directories, Scripts, bin, and condabin.

Disabled Shell Commands#

Generated runtimes use conda-spawn for activation. When the delegate is conda, these commands are intercepted with runtime-specific guidance instead of being passed through:

  • RUNTIME activate

  • RUNTIME deactivate

  • RUNTIME init

Use RUNTIME shell ENV instead of conda activate ENV.