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.

domyn-swarm

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.

db

Manage the Domyn-Swarm state database.

Usage

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

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.

Default:

False

stamp

Usage

domyn-swarm db stamp [OPTIONS]

upgrade

Usage

domyn-swarm db upgrade [OPTIONS]

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]

Options

-y, --yes

Force shutdown without confirmation.

Default:

False

--select

Pick a single swarm when multiple matches.

Default:

False

--all

Tear down all matching swarms.

Default:

False

-c, --config <config>

Path to YAML config (must contain ‘name’).

Arguments

NAME

Optional argument

Swarm name.

init

Initialize a new Domyn-Swarm configuration.

Usage

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

defaults

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

Usage

domyn-swarm init defaults [OPTIONS]

Options

-o, --output <output>

Path to save the defaults YAML configuration file.

--force

Overwrite existing file if it exists.

Default:

False

job

Submit a workload to a Domyn-Swarm allocation.

Usage

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

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]

Options

--external-id <external_id>

Provider external ID (for example Slurm step id).

--handle-json <handle_json>

JSON handle payload (use ‘-’ to read from stdin). If omitted, stdin is auto-read.

-n, --name <name>

Optional deployment name used to disambiguate –external-id or handle payload.

Arguments

JOB_ID

Optional argument

Internal Domyn job ID from the local state DB.

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 <name>

Required Swarm deployment name.

--status <status>

Filter by status (repeatable). Values: PENDING,RUNNING,SUCCEEDED,FAILED,CANCELLED.

--limit <limit>

Maximum number of jobs to return.

Default:

50

--json

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

Default:

False

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

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.

Default:

False

--json

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

Default:

False

Arguments

JOB_ID

Required argument

Internal Domyn job ID from the local state DB.

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]

Options

--input <input>

Required

--output <output>

Required

--input-column <input_column>

Default:

'messages'

--output-column <output_column>

Default:

'results'

--id-column, --id-col <id_column>

Optional column name used for stable row ids.

--job-kwargs <job_kwargs>

JSON dict forwarded to job constructor

Default:

'{}'

--data-backend <data_backend>

Data backend for IO (pandas, polars, ray).

--native-backend, --no-native-backend

Use native backend batches when supported.

--native-batch-size <native_batch_size>

Batch size for native backend mode (optional).

--backend-read-kwargs <backend_read_kwargs>

JSON dict forwarded to backend read() call.

--backend-write-kwargs <backend_write_kwargs>

JSON dict forwarded to backend write() call.

--job-name <job_name>

Optional job name for logging

-c, --config <config>

YAML that starts a fresh swarm

-n, --name <name>

Swarm name.

-cd, --checkpoint-dir <checkpoint_dir>

Directory to store checkpoints (default: .checkpoint/, no checkpoints)

--no-resume, --ignore-checkpoints

Ignore existing checkpoints for this run (forces recompute).

Default:

False

--no-checkpointing

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

Default:

False

--runner <runner>

Runner implementation for non-ray backends (pandas, arrow).

Default:

'pandas'

-ci, --checkpoint-interval <checkpoint_interval>

Batch size for processing input DataFrame (default: 32)

Default:

32

-mc, --max-concurrency <max_concurrency>

Number of concurrent requests to process (default: 32)

Default:

32

-r, --retries <retries>

Number of retries for failed requests (default: 5)

Default:

5

-t, --timeout <timeout>

Timeout for each request in seconds (default: 600)

Default:

600

-nt, --num-threads <num_threads>

How many threads should be used by the driver to run the job

Default:

1

--shard-output

When output is a directory and using the Polars runner, write one parquet file per shard (based on –num-threads) using checkpoint outputs as the source of truth.

Default:

False

-l, --limit <limit>

Limit the size to be read from the input dataset. Useful when debugging and testing to reduce the size of the dataset

--shard-mode <shard_mode>

How to split input when –num-threads > 1. ‘id’ uses stable id hashing (resume-friendly), ‘index’ uses legacy row order sharding. Keep –num-threads fixed across resumes to avoid reshuffling shards.

Default:

'id'

Options:

id | index

--global-resume

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

Default:

False

-d, --detach

Detach the job from the current terminal

Default:

False

-m, --mail-user <mail_user>

Email address to receive job notifications. If set, email notifications will be enabled.

--checkpoint-tag <checkpoint_tag>

An optional tag to be used when checkpointing is enabled. It will be used in place of the default uuid-based tag.

--ray-address <ray_address>

Ray cluster address to connect to when –data-backend=ray (optional).

Arguments

JOB_CLASS

Optional argument

Job class to run, in the form module:ClassName

submit-script

Run an arbitrary Python file inside the swarm head node.

Usage

domyn-swarm job submit-script [OPTIONS] SCRIPT_FILE [ARGS]...

Options

-c, --config <config>

YAML that defines/creates a new swarm

-n, --name <name>

Swarm name.

Arguments

SCRIPT_FILE

Required argument

ARGS

Optional argument(s)

extra CLI args passed to script

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 <job_id>

Internal Domyn job ID from the local state DB.

--external-id <external_id>

Provider external ID (for example Slurm step id).

--handle-json <handle_json>

JSON handle payload (use ‘-’ to read from stdin). If omitted, stdin is auto-read.

-n, --name <name>

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:

True

monitor

Launch grafatui pointed at the swarm’s Prometheus endpoint.

Usage

domyn-swarm monitor [OPTIONS] NAME

Options

-d, --dashboard <dashboard>

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.

Default:

False

--prometheus-url <prometheus_url>

Override the resolved Prometheus URL.

--range <range_>

grafatui time range, e.g. 1h.

--step <step>

grafatui query step, e.g. 15s.

--var <var>

Override a dashboard variable as KEY=VALUE (repeatable). Auto-filled defaults: vllm_job, replicas.

Arguments

NAME

Required argument

Swarm name to monitor.

pool

Submit a pool of swarm allocations from a YAML config.

Usage

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

pool

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

Usage

domyn-swarm pool pool [OPTIONS] CONFIG

Arguments

CONFIG

Required argument

Path to YAML config for a pool of swarm allocations

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

Options

-o, --output <output>

Output format: ‘table’ (default, Rich TUI) or ‘json’ (stable, machine-readable).

Default:

'table'

Arguments

NAME

Required argument

Name of the swarm allocation to check status for.

swarm

Manage swarm allocations.

Usage

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

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

Options

-o, --output <output>

Output format: table (default), yaml, or json.

Default:

'table'

Options:

table | yaml | json

Arguments

NAME

Required argument

Name of the swarm to describe.

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:

True

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 <config>

Required Path to YAML config for LLMSwarmConfig

-r, --replicas <replicas>

Number of replicas for the swarm allocation. Defaults to 1.

version

Show the version of the domyn-swarm CLI

Usage

domyn-swarm version [OPTIONS]

Options

--short, --no-short

Default:

False