CLI#

Generated from the Typer application, so every command and flag below exists in the installed version.

domyn-swarm pool pool is present but incomplete — it brings a pool up and immediately tears it down again, with no way to submit work to it.

Main entrypoint

Usage:

$ domyn-swarm [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.

  • --show-completion: Show completion for the current shell, to copy it or customize the installation.

  • --help: Show this message and exit.

Commands:

  • db: Manage the Domyn-Swarm state database.

  • down: Shut down a swarm allocation

  • init: Initialize a new Domyn-Swarm configuration.

  • job: Submit a workload to a Domyn-Swarm…

  • monitor: Open grafatui against a swarm’s Prometheus

  • pool: Submit a pool of swarm allocations from a…

  • status: Check the status of the swarm allocation given its state file

  • swarm: Manage swarm allocations.

  • up: Launch a swarm allocation with a configuration

  • version: Show the version of the domyn-swarm CLI

domyn-swarm db#

Manage the Domyn-Swarm state database.

Usage:

$ domyn-swarm db [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • upgrade

  • stamp

  • prune: Delete swarm records with FAILED, STOPPED,…

domyn-swarm db upgrade#

Usage:

$ domyn-swarm db upgrade [OPTIONS]

Options:

  • --help: Show this message and exit.

domyn-swarm db stamp#

Usage:

$ domyn-swarm db stamp [OPTIONS]

Options:

  • --help: Show this message and exit.

domyn-swarm db prune#

Delete swarm records with FAILED, STOPPED, or UNKNOWN live status.

Args: yes (bool): Skip confirmation prompt when True.

Usage:

$ domyn-swarm db prune [OPTIONS]

Options:

  • -y, --yes: Skip confirmation prompt before deleting records.

  • --help: Show this message and exit.

domyn-swarm down#

Shut down a swarm allocation.

If NAME is not provided, attempts to find the last created swarm. If a CONFIG is provided, uses its ‘name’ field to find matching swarms. Use –all to shut down all matching swarms, or –select to pick one interactively.

Usage:

$ domyn-swarm down [OPTIONS] [name]

Arguments:

  • name <str>: Swarm name.

Options:

  • -y, --yes: Force shutdown without confirmation.

  • --select: Pick a single swarm when multiple matches.

  • --all: Tear down all matching swarms.

  • -c, --config <FileText>: Path to YAML config (must contain ‘name’).

  • --help: Show this message and exit.

domyn-swarm init#

Initialize a new Domyn-Swarm configuration.

Usage:

$ domyn-swarm init [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • defaults: Create a defaults.yaml configuration file…

domyn-swarm init defaults#

Create a defaults.yaml configuration file to be used later.

Usage:

$ domyn-swarm init defaults [OPTIONS]

Options:

  • -o, --output <str>: Path to save the defaults YAML configuration file.

  • --force: Overwrite existing file if it exists.

  • --help: Show this message and exit.

domyn-swarm job#

Submit a workload to a Domyn-Swarm allocation.

Usage:

$ domyn-swarm job [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • submit-script: Run an arbitrary Python file inside the…

  • submit: Submit a strongly-typed job to the swarm…

  • list: List jobs for a swarm.

  • status: Show details for a recorded job.

  • wait: Wait for a submitted job to reach a…

  • cancel: Cancel a submitted job.

domyn-swarm job submit-script#

Run an arbitrary Python file inside the swarm head node.

Usage:

$ domyn-swarm job submit-script [OPTIONS] {script_file} [args]...

Arguments:

  • script_file <path>: [required]

  • args... <list[str]>: extra CLI args passed to script

Options:

  • -c, --config <FileText>: YAML that defines/creates a new swarm

  • -n, --name <str>: Swarm name.

  • --skip-preflight: Deploy without checking that the config’s image, model and mount paths exist on this host. Only relevant with –config.

  • --mem <str>: Slurm only. Memory for the job step, for example 64G. 0 gives the step all the memory of its allocation. Default: 0 with endpoint.require_allocated_node, otherwise endpoint.mem.

  • --cpus-per-task <int range>: Slurm only. CPUs for the job step. Default: the --cpus-per-task value of the enclosing allocation with endpoint.require_allocated_node, otherwise endpoint.cpus_per_task. [x>=1]

  • --help: Show this message and exit.

domyn-swarm job submit#

Submit a strongly-typed job to the swarm for DataFrame processing.

This command processes input data through a SwarmJob (DataFrame-in → DataFrame-out) within the swarm environment. Jobs are defined by a class that handles the actual processing logic, and the input/output are managed as DataFrames with configurable column mappings.

The job can either create a new swarm from a configuration file or connect to an existing swarm by name. Progress is tracked through checkpoints, and the operation supports concurrent processing with configurable retry logic.

Usage:

$ domyn-swarm job submit [OPTIONS] [job_class]

Arguments:

  • job_class <str>: Job class to run, in the form module:ClassName [default: domyn_swarm.jobs:ChatCompletionJob]

Options:

  • --input ENVPATH: [required]

  • --output ENVPATH: [required]

  • --input-column <str>: [default: messages]

  • --output-column <str>: [default: results]

  • --id-column, --id-col <str>: Optional column name used for stable row ids.

  • --job-kwargs <str>: JSON dict forwarded to job constructor [default: {}]

  • --data-backend <str>: Data backend for IO (pandas, polars, ray).

  • --native-backend / --no-native-backend: Use native backend batches when supported.

  • --native-batch-size <int>: Batch size for native backend mode (optional).

  • --backend-read-kwargs <str>: JSON dict forwarded to backend read() call.

  • --backend-write-kwargs <str>: JSON dict forwarded to backend write() call.

  • --job-name <str>: Optional job name for logging

  • -c, --config <FileText>: YAML that starts a fresh swarm

  • -n, --name <str>: Swarm name.

  • -cd, --checkpoint-dir <path>: Directory to store checkpoints (default: .checkpoint/, no checkpoints)

  • --no-resume, --ignore-checkpoints: Ignore existing checkpoints for this run (forces recompute).

  • --no-checkpointing: Disable checkpointing entirely (no read/write checkpoint state).

  • --runner <str>: Deprecated; use –engine instead. Runner implementation for non-ray backends (pandas, arrow). [default: pandas]

  • --engine <str>: Execution engine to use (pandas, arrow, polars, ray). Takes precedence over the deprecated –runner/–data-backend pair.

  • -ci, --checkpoint-interval <int>: Batch size for processing input DataFrame (default: 32) [default: 32]

  • -mc, --max-concurrency <int>: Number of concurrent requests to process (default: 32) [default: 32]

  • -r, --retries <int>: Number of retries for failed requests (default: 5) [default: 5]

  • -t, --timeout <float>: Timeout for each request in seconds (default: 600) [default: 600]

  • -ns, --num-shards <int>: How many shards to split the input into. This is part of the checkpoint layout: keep it fixed across resumes of the same job, or completed rows will be reprocessed. [default: 1]

  • --shard-output: When output is a directory, write shards directly from checkpoint outputs instead of assembling the merged result in memory first. Supported by the pandas and polars runners; ignored by the arrow runner. Either way the directory is written as one parquet file per shard (based on –num-shards). On the pandas and polars runners this also makes –global-resume a no-op: per-shard checkpoint resume alone already covers it, as long as –num-shards stays fixed across resumes.

  • -l, --limit <int>: Limit the size to be read from the input dataset. Useful when debugging and testing to reduce the size of the dataset

  • --shard-mode <id|index>: How to split input when –num-shards > 1. ‘id’ uses stable id hashing (resume-friendly), ‘index’ uses legacy row order sharding. Keep –num-shards fixed across resumes to avoid reshuffling shards. [default: id]

  • --global-resume: When resuming with sharded execution, filter inputs using global done ids across all shards (useful if –limit changed).

  • -d, --detach: Detach the job from the current terminal

  • -m, --mail-user <str>: Email address to receive job notifications. If set, email notifications will be enabled.

  • --checkpoint-tag <str>: An optional tag to be used when checkpointing is enabled. It will be used in place of the default uuid-based tag.

  • --ray-address <str>: Ray cluster address to connect to when –data-backend=ray (optional).

  • --skip-preflight: Deploy without checking that the config’s image, model and mount paths exist on this host. Only relevant with –config.

  • --mem <str>: Slurm only. Memory for the job step, for example 64G. 0 gives the step all the memory of its allocation. Default: 0 with endpoint.require_allocated_node, otherwise endpoint.mem.

  • --cpus-per-task <int range>: Slurm only. CPUs for the job step. Default: the --cpus-per-task value of the enclosing allocation with endpoint.require_allocated_node, otherwise endpoint.cpus_per_task. [x>=1]

  • --help: Show this message and exit.

domyn-swarm job list#

List jobs for a swarm.

Args: name: Swarm deployment name. status: Optional status filter list. limit: Maximum number of jobs to show. json_output: Whether to emit JSON output.

Usage:

$ domyn-swarm job list [OPTIONS]

Options:

  • -n, --name <str>: Swarm deployment name. [required]

  • --status <list[str]>: Filter by status (repeatable). Values: PENDING,RUNNING,SUCCEEDED,FAILED,CANCELLED.

  • --limit <int range>: Maximum number of jobs to return. [default: 50; x>=1]

  • --json: Output machine-parseable JSON instead of the default TUI view.

  • --help: Show this message and exit.

domyn-swarm job status#

Show details for a recorded job.

Args: job_id: Internal job ID. refresh: Whether to probe the backend for live status before display. json_output: Whether to emit JSON output.

Usage:

$ domyn-swarm job status [OPTIONS] {job_id}

Arguments:

  • job_id <str>: Internal Domyn job ID from the local state DB. [required]

Options:

  • --refresh: Probe the backend for live status and persist it to the local state DB. By default the recorded status is shown without contacting the backend.

  • --json: Output machine-parseable JSON instead of the default TUI view.

  • --help: Show this message and exit.

domyn-swarm job wait#

Wait for a submitted job to reach a terminal state.

Args: job_id: Internal job ID selector. external_id: Provider external-id selector. handle_json: Handle JSON selector, literal payload or stdin marker. name: Optional deployment name hint. stream_logs: Whether to stream backend logs while waiting.

Usage:

$ domyn-swarm job wait [OPTIONS]

Options:

  • --job-id <str>: Internal Domyn job ID from the local state DB.

  • --external-id <str>: Provider external ID (for example Slurm step id).

  • --handle-json <str>: JSON handle payload (use ‘-’ to read from stdin). If omitted, stdin is auto-read.

  • -n, --name <str>: Optional deployment name used to disambiguate –external-id or handle payload.

  • --stream-logs / --no-stream-logs: Stream backend logs while waiting (when supported by backend). [default: stream-logs]

  • --help: Show this message and exit.

domyn-swarm job cancel#

Cancel a submitted job.

Args: job_id: Internal job ID selector (positional). external_id: Provider external-id selector. handle_json: Handle JSON selector, literal payload or stdin marker. name: Optional deployment name hint.

Usage:

$ domyn-swarm job cancel [OPTIONS] [job_id]

Arguments:

  • job_id <str>: Internal Domyn job ID from the local state DB.

Options:

  • --external-id <str>: Provider external ID (for example Slurm step id).

  • --handle-json <str>: JSON handle payload (use ‘-’ to read from stdin). If omitted, stdin is auto-read.

  • -n, --name <str>: Optional deployment name used to disambiguate –external-id or handle payload.

  • --help: Show this message and exit.

domyn-swarm monitor#

Launch grafatui pointed at the swarm’s Prometheus endpoint.

Usage:

$ domyn-swarm monitor [OPTIONS] {name}

Arguments:

  • name <str>: Swarm name to monitor. [required]

Options:

  • -d, --dashboard <path>: Custom Grafana dashboard JSON to load. Defaults to the bundled vLLM dashboard.

  • -g, --gpu: Load the GPU dashboard for the swarm’s configured gpu_exporter kind.

  • --prometheus-url <str>: Override the resolved Prometheus URL.

  • --range <str>: grafatui time range, e.g. 1h.

  • --step <str>: grafatui query step, e.g. 15s.

  • --var <list[str]>: Override a dashboard variable as KEY=VALUE (repeatable). Auto-filled defaults: vllm_job, replicas.

  • --help: Show this message and exit.

domyn-swarm pool#

Submit a pool of swarm allocations from a YAML config.

Usage:

$ domyn-swarm pool [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • pool: Deploy a pool of swarm allocations from a YAML config (not yet implemented)

domyn-swarm pool pool#

Usage:

$ domyn-swarm pool pool [OPTIONS] {config}

Arguments:

  • config <FileText>: Path to YAML config for a pool of swarm allocations [required]

Options:

  • --help: Show this message and exit.

domyn-swarm status#

Check the status of the swarm allocation.

This command will read the DB and print the status of the swarm allocation. If a name is provided, it will check the status of that specific allocation.

Usage:

$ domyn-swarm status [OPTIONS] {name}

Arguments:

  • name <str>: Name of the swarm allocation to check status for. [required]

Options:

  • -o, --output <str>: Output format: ‘table’ (default, Rich TUI) or ‘json’ (stable, machine-readable). [default: table]

  • --help: Show this message and exit.

domyn-swarm swarm#

Manage swarm allocations.

Usage:

$ domyn-swarm swarm [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List all known swarms in a compact table…

  • describe: Show a detailed, static description of a…

domyn-swarm swarm list#

List all known swarms in a compact table (name, backend, phase, endpoint, notes).

Usage:

$ domyn-swarm swarm list [OPTIONS]

Options:

  • --probe / --no-probe: Probe live status (HTTP/LB/etc.). Disable for faster listing. [default: probe]

  • --help: Show this message and exit.

domyn-swarm swarm describe#

Show a detailed, static description of a swarm from the local state. No live status probing (use domyn-swarm status for that).

Usage:

$ domyn-swarm swarm describe [OPTIONS] {name}

Arguments:

  • name <str>: Name of the swarm to describe. [required]

Options:

  • -o, --output <table|yaml|json>: Output format: table (default), yaml, or json. [default: table]

  • --help: Show this message and exit.

domyn-swarm up#

Launch a swarm allocation with the given configuration. The configuration must be provided as a YAML file.

Usage:

$ domyn-swarm up [OPTIONS]

Options:

  • -c, --config <FileText>: Path to YAML config for LLMSwarmConfig [required]

  • -r, --replicas <int>: Number of replicas for the swarm allocation. Defaults to 1.

  • --skip-preflight: Submit without checking that the config’s image, model and mount paths exist on this host.

  • --help: Show this message and exit.

domyn-swarm version#

Usage:

$ domyn-swarm version [OPTIONS]

Options:

  • --short / --no-short: [default: no-short]

  • --help: Show this message and exit.