Builder CLI Reference#

The cs CLI builds and stages conda runtimes.

This page covers the builder CLI. For the command surface exposed by generated runtimes, see Runtime CLI Reference.

The conda-ship package can also make conda ship available as a conda-style shortcut for this CLI. See conda ship Reference.

Packaged cs builds find the installed runtime template next to the cs executable. Pass --template only when you need to override that template, use an explicit release asset, or cross-build for another target.

cs inspect#

Inspect the project input and derived runtime package set without writing files. Use this as a preflight check before a local build or release job.

cs inspect [--platform PLATFORM] [--json] [--root PATH]

Options:

  • --platform PLATFORM: inspect a conda platform such as linux-64.

  • --json: emit machine-readable JSON with project input, validation, exclusions, platform summaries, and packages for the selected platform.

  • --root PATH: use a build root instead of auto-detecting one.

cs build#

Build and stage a runtime artifact.

cs build [--runtime RUNTIME] [--delegate EXECUTABLE] [--layout LAYOUT] [--target-label LABEL] \
  [--platform PLATFORM] [--target TRIPLE] [--template PATH] \
  [--runtime-version VERSION] [--docs-url URL] [--install-scheme SCHEME] \
  [--install-name NAME] [--install-method METHOD] \
  [--out-dir PATH] [--dry-run] [--root PATH]

Identifier-like values such as RUNTIME, EXECUTABLE, LABEL, TRIPLE, and METHOD must start with an ASCII letter or digit and may only contain ASCII letters, digits, ., _, and -. RUNTIME names the generated runtime; it is not a conda environment name. Runtime metadata can come from CLI flags or [tool.conda-ship].

Options:

  • --runtime RUNTIME: override [tool.conda-ship].runtime.

  • --delegate EXECUTABLE: override [tool.conda-ship].delegate.

  • --runtime-version VERSION: version shown by the generated runtime. Overrides [tool.conda-ship].runtime-version, [project].version, and project metadata resolution.

  • --layout online: stage a runtime that downloads packages during bootstrap.

  • --layout external: stage a runtime plus compressed bundle.

  • --layout embedded: stage a runtime with the compressed bundle embedded. When omitted, cs uses [tool.conda-ship].layout or online.

  • --target-label LABEL: append a platform or target label to artifact names.

  • --platform PLATFORM: choose the conda platform for metadata and bundles.

  • --target TRIPLE: target triple used for artifact naming and template selection. It also selects the staged .exe suffix for Windows artifacts. Path-like custom target specifications are not supported here.

  • --template PATH: prebuilt generic runtime template binary to copy and stamp. When omitted, packaged builds use the template installed next to cs.

  • --docs-url URL: documentation URL stamped into runtime help output. Must start with https:// or http:// and must not contain whitespace or control characters.

  • --install-scheme SCHEME: install scheme stamped into the runtime. Currently supported: conda-home, which installs below ~/.conda/INSTALL_NAME, and user-data, which installs below the platform user data directory.

  • --install-name NAME: name used inside the install scheme. Defaults to RUNTIME.

  • --install-method METHOD: package-manager or installer method stamped into the runtime for uninstall guidance. Overrides [tool.conda-ship].install-method.

  • --out-dir PATH: write staged artifacts somewhere other than dist/.

  • --dry-run: validate the build input and print the planned artifacts without downloading, stamping, or writing files.

  • --root PATH: use a project root instead of auto-detecting one.

cs run#

Build a runtime artifact and execute it immediately.

cs run [--runtime RUNTIME] [--delegate EXECUTABLE] [--layout LAYOUT] [--platform PLATFORM] \
  [--template PATH] [--runtime-version VERSION] [--docs-url URL] \
  [--install-scheme SCHEME] [--install-name NAME] [--install-method METHOD] \
  [--out-dir PATH] [--root PATH] \
  -- RUNTIME_ARGS...

Everything after -- is passed to the staged runtime.

Options:

  • --runtime RUNTIME: override [tool.conda-ship].runtime.

  • --delegate EXECUTABLE: override [tool.conda-ship].delegate.

  • --runtime-version VERSION: version shown by the generated runtime. Overrides [tool.conda-ship].runtime-version, [project].version, and project metadata resolution.

  • --layout online: stage a runtime that downloads packages during bootstrap.

  • --layout external: stage a runtime plus compressed bundle.

  • --layout embedded: stage a runtime with the compressed bundle embedded. When omitted, cs uses [tool.conda-ship].layout or online.

  • --platform PLATFORM: choose the conda platform for metadata and bundles.

  • --template PATH: prebuilt generic runtime template binary to copy and stamp. When omitted, packaged builds use the template installed next to cs.

  • --docs-url URL: documentation URL stamped into runtime help output. Must start with https:// or http:// and must not contain whitespace or control characters.

  • --install-scheme SCHEME: install scheme stamped into the runtime. Currently supported: conda-home and user-data.

  • --install-name NAME: name used inside the install scheme. Defaults to RUNTIME.

  • --install-method METHOD: package-manager or installer method stamped into the runtime for uninstall guidance.

  • --out-dir PATH: write staged artifacts somewhere other than dist/.

  • --root PATH: use a project root instead of auto-detecting one.

  • RUNTIME_ARGS: arguments passed to the staged runtime after it is built.