zeroshot CLI reference¶
This reference is generated from the typed Clap command model and its Rust doc comments.
Regenerate it with cargo run -p zeroshot --example generate_cli_docs -- --write.
zeroshot¶
Run multi-agent graphs locally or on named Zeroshot targets.
Single-result commands write JSON. Foreground `run`, `watch`, `logs`, and `attach` stream newline-delimited JSON (NDJSON).
Usage: zeroshot [COMMAND]
Commands:
target Manage named targets or serve a direct target
connection Inspect and manage named runtime connections
profile Manage reusable graph/runtime profiles
template Inspect built-in graph templates
plan Validate, submit, and observe hosted merge plans
run Submit a graph run locally or to a named target
list List runs as JSON
status Read a run's current status as JSON
watch Follow a run's durable event stream as NDJSON
logs Follow a run's log stream as NDJSON
attach Attach to an execution's interactive event stream as NDJSON
force-stop Force a run to stop and write the result as JSON
version Print the Zeroshot version
help Print this message or the help of the given subcommand(s)
Options:
-V, --version
Print the Zeroshot version
-h, --help
Print help (see a summary with '-h')
zeroshot target¶
Manage named targets or serve a direct target.
The built-in `cloud` target points to https://api.cloud.zeroshot.sh. Run `zeroshot target login cloud` to sign in.
Usage: zeroshot target <COMMAND>
Commands:
add Register a named target
login Authenticate with a hosted named target
serve Serve an unauthenticated direct target
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
zeroshot target add¶
Register a named target
Usage: zeroshot target add [OPTIONS] --url <ORIGIN> <NAME>
Arguments:
<NAME>
Local name used to select this target
Options:
--url <ORIGIN>
Target origin URL
--direct
Use unauthenticated direct access instead of hosted authentication
-h, --help
Print help
zeroshot target login¶
Authenticate with a hosted named target.
On Linux, desktop sessions prefer Secret Service and headless sessions use a durable private file. Set ZEROSHOT_CREDENTIAL_STORE to auto, system, or file to override automatic selection.
Usage: zeroshot target login <NAME>
Arguments:
<NAME>
Local target name
Options:
-h, --help
Print help (see a summary with '-h')
zeroshot target serve¶
Serve an unauthenticated direct target.
Direct mode is unauthenticated. Bind or publish it only on trusted networks.
Usage: zeroshot target serve --listen <ADDRESS> --public-origin <ORIGIN> --storage <DIRECTORY>
Options:
--listen <ADDRESS>
IP socket address on which the target listens
--public-origin <ORIGIN>
Public HTTP(S) origin advertised to clients
--storage <DIRECTORY>
Directory that stores target state and run data
-h, --help
Print help (see a summary with '-h')
zeroshot target help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot target help [COMMAND]
Commands:
add Register a named target
login Authenticate with a hosted named target
serve Serve an unauthenticated direct target
help Print this message or the help of the given subcommand(s)
zeroshot connection¶
Inspect and manage named runtime connections
Usage: zeroshot connection <COMMAND>
Commands:
list List connection metadata without secret values
set Create or replace one static connection
delete Delete one connection
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
CONNECTIONS
A runtime declares a connection key and the exact environment fields it needs. Zeroshot injects
only those fields; secret values never belong in runtime configuration.
`list` returns each key, scope, kind, and field names, never secret values. `set` creates or replaces
a complete static connection, so include every required field. Omit --target for local storage; use
--target NAME for hosted storage. Organization scope requires a hosted target.
Target-managed dynamic kinds are configured through the target rather than `connection set`; `list`
reports each connection's kind.
When a run reports `connection_unavailable`, list connections for the same target and scope, then
set the named key with every required field.
EXAMPLES
zeroshot connection list
zeroshot connection list --target prod --scope org
zeroshot connection set openrouter --field OPENROUTER_API_KEY
zeroshot connection set openrouter --target prod --field OPENROUTER_API_KEY
zeroshot connection list¶
List connection metadata without secret values
Usage: zeroshot connection list [OPTIONS]
Options:
--target <NAME>
Use this named hosted target. If omitted, use local connections
--scope <SCOPE>
Select user- or organization-scoped connections
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot connection set¶
Create or replace one static connection
Usage: zeroshot connection set [OPTIONS] <--field <ENV>|--json-stdin> <KEY>
Arguments:
<KEY>
Unique connection key within the selected scope
Options:
--field <ENV>
Prompt without echo for this environment field. Repeat for multiple fields
--json-stdin
Read one JSON object of environment field names to secret values from standard input
--target <NAME>
Use this named hosted target. If omitted, use local connections
--scope <SCOPE>
Select user- or organization-scoped connections
[default: user]
[possible values: user, org]
-h, --help
Print help (see a summary with '-h')
INPUT
Use --field ENV to prompt without echo; repeat it for every required field. Use --json-stdin to read
one non-empty JSON object mapping field names to secret values.
`set` replaces the complete stored static connection for KEY. Existing fields not supplied are
removed. Do not put secret values in shell arguments or runtime configuration.
zeroshot connection delete¶
Delete one connection
Usage: zeroshot connection delete [OPTIONS] <KEY>
Arguments:
<KEY>
Unique connection key within the selected scope
Options:
--target <NAME>
Use this named hosted target. If omitted, use local connections
--scope <SCOPE>
Select user- or organization-scoped connections
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot connection help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot connection help [COMMAND]
Commands:
list List connection metadata without secret values
set Create or replace one static connection
delete Delete one connection
help Print this message or the help of the given subcommand(s)
zeroshot profile¶
Manage reusable graph/runtime profiles
Usage: zeroshot profile <COMMAND>
Commands:
list List profile metadata
set Create or replace a fully materialized profile
show Show one profile with its graph and runtime
remove Remove one profile
default Set the scope's default profile, or clear it when NAME is omitted
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
zeroshot profile list¶
List profile metadata
Usage: zeroshot profile list [OPTIONS]
Options:
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Select user- or organization-scoped hosted profiles
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot profile set¶
Create or replace a fully materialized profile
Usage: zeroshot profile set [OPTIONS] <--graph <FILE>|--template <TEMPLATE>> <--runtime-config <FILE>|--uniform-runtime-config <FILE>> <NAME>
Arguments:
<NAME>
Options:
--graph <FILE>
--template <TEMPLATE>
Possible values:
- single-worker: A single general-purpose worker
- software-change: A review, validation, and optional delivery workflow for code changes
--runtime-config <FILE>
--uniform-runtime-config <FILE>
--default
--delivery <MODE>
Materialize this template-owned delivery mode
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template.
Named-target runs forward GH_TOKEN for the generated GitHub merge operation.
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Select user- or organization-scoped hosted profiles
[default: user]
[possible values: user, org]
-h, --help
Print help (see a summary with '-h')
zeroshot profile show¶
Show one profile with its graph and runtime
Usage: zeroshot profile show [OPTIONS] <NAME>
Arguments:
<NAME>
Profile name
Options:
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Select user- or organization-scoped hosted profiles
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot profile remove¶
Remove one profile
Usage: zeroshot profile remove [OPTIONS] <NAME>
Arguments:
<NAME>
Profile name
Options:
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Select user- or organization-scoped hosted profiles
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot profile default¶
Set the scope's default profile, or clear it when NAME is omitted
Usage: zeroshot profile default [OPTIONS] [NAME]
Arguments:
[NAME]
Profile name. Omit to clear the selected scope's default
Options:
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Select user- or organization-scoped hosted profiles
[default: user]
[possible values: user, org]
-h, --help
Print help
zeroshot profile help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot profile help [COMMAND]
Commands:
list List profile metadata
set Create or replace a fully materialized profile
show Show one profile with its graph and runtime
remove Remove one profile
default Set the scope's default profile, or clear it when NAME is omitted
help Print this message or the help of the given subcommand(s)
zeroshot template¶
Inspect built-in graph templates
Usage: zeroshot template <COMMAND>
Commands:
list List built-in template names as JSON
show Write a built-in graph template as JSON
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
zeroshot template list¶
zeroshot template show¶
Write a built-in graph template as JSON
Usage: zeroshot template show [OPTIONS] <TEMPLATE>
Arguments:
<TEMPLATE>
Built-in graph template to render
Possible values:
- single-worker: A single general-purpose worker
- software-change: A review, validation, and optional delivery workflow for code changes
Options:
--delivery <MODE>
Materialize this template-owned delivery mode
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template.
Named-target runs forward GH_TOKEN for the generated GitHub merge operation.
-h, --help
Print help (see a summary with '-h')
zeroshot template help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot template help [COMMAND]
Commands:
list List built-in template names as JSON
show Write a built-in graph template as JSON
help Print this message or the help of the given subcommand(s)
zeroshot plan¶
Validate, submit, and observe hosted merge plans
Usage: zeroshot plan <COMMAND>
Commands:
validate Validate a merge-plan manifest without contacting a target
submit Atomically submit every node in a merge-plan manifest
status Read a merge plan's aggregate status as JSON
watch Poll a merge plan and stream changed snapshots as NDJSON
force-stop Force every nonterminal run in a merge plan to stop
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
MANIFEST
The JSON manifest is strict and self-contained:
{
"schema": "zeroshot.merge-plan/v1",
"title": "Release checkout update",
"source": {"repository": "owner/repo", "branch": "main"},
"profile": "org:software-change",
"expiresAt": "<RFC3339 timestamp within 7 days>",
"runs": {
"backend": {"input": {"task": "Update the API."}},
"integrate": {"needs": ["backend"], "input": {"task": "Run release tests."}}
}
}
Every run uses the same source and profile. The profile must contain exactly one `builtin.git-delivery.merge@2` node;
pull-request delivery is rejected. Agent bindings must not declare `GH_TOKEN`; only the Git delivery
binding may declare it. `needs` gates readiness but does not pass output between runs.
Cloud assigns every run ID atomically at submission. After a node's dependencies succeed, Cloud
materializes it against an exact source revision. Once materialization completes, `readyAt` is set
and the node's queue deadline is the earlier of `expiresAt` and seven days after `readyAt`.
`expiresAt` must be in the future and no more than
seven days away. Plans cannot be edited or retried in place.
zeroshot plan validate¶
Validate a merge-plan manifest without contacting a target
Usage: zeroshot plan validate <FILE>
Arguments:
<FILE>
Merge-plan manifest JSON file
Options:
-h, --help
Print help
zeroshot plan submit¶
Atomically submit every node in a merge-plan manifest
Usage: zeroshot plan submit [OPTIONS] --target <NAME> --submission-key <KEY> <FILE>
Arguments:
<FILE>
Merge-plan manifest JSON file
Options:
--target <NAME>
Submit to this named hosted target
--submission-key <KEY>
Stable idempotency key for safely retrying the atomic submission
-d, --detach
Return after atomic submission instead of polling plan status
-h, --help
Print help
zeroshot plan status¶
Read a merge plan's aggregate status as JSON
Usage: zeroshot plan status --target <NAME> <PLAN_ID>
Arguments:
<PLAN_ID>
Immutable merge-plan ID
Options:
--target <NAME>
Use this named hosted target
-h, --help
Print help
zeroshot plan watch¶
Poll a merge plan and stream changed snapshots as NDJSON
Usage: zeroshot plan watch --target <NAME> <PLAN_ID>
Arguments:
<PLAN_ID>
Immutable merge-plan ID
Options:
--target <NAME>
Use this named hosted target
-h, --help
Print help
zeroshot plan force-stop¶
Force every nonterminal run in a merge plan to stop
Usage: zeroshot plan force-stop --target <NAME> <PLAN_ID>
Arguments:
<PLAN_ID>
Immutable merge-plan ID
Options:
--target <NAME>
Use this named hosted target
-h, --help
Print help
zeroshot plan help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot plan help [COMMAND]
Commands:
validate Validate a merge-plan manifest without contacting a target
submit Atomically submit every node in a merge-plan manifest
status Read a merge plan's aggregate status as JSON
watch Poll a merge plan and stream changed snapshots as NDJSON
force-stop Force every nonterminal run in a merge plan to stop
help Print this message or the help of the given subcommand(s)
zeroshot run¶
Submit a graph run locally or to a named target.
When --target is omitted, the run uses the current local repository. A foreground run follows NDJSON events until completion. --detach returns after submission; Ctrl-C also detaches from observation without stopping the run. Named-target runs send GH_TOKEN, when set, for source checkout and Git delivery; providers receive it only when the runtime declares GH_TOKEN.
Usage: zeroshot run [OPTIONS] --title <TITLE> --input <FILE>
Options:
--title <TITLE>
Human-readable title recorded with the run
--graph <FILE>
Load a custom graph specification from this JSON file
--template <TEMPLATE>
Materialize and run this built-in graph template
Possible values:
- single-worker: A single general-purpose worker
- software-change: A review, validation, and optional delivery workflow for code changes
--input <FILE>
Load the graph's initial input from this JSON file
--runtime-config <FILE>
Load an exact secret-free runtime plan from this JSON file
--uniform-runtime-config <FILE>
Expand one secret-free agent runtime across every executable graph node
--profile <[SCOPE:]NAME>
Use a profile: NAME, local:NAME, user:NAME, or org:NAME.
When no profile or inline graph/runtime is supplied, scoped defaults are checked.
--target <NAME>
Run on this named target; if omitted, run locally. Named targets receive GH_TOKEN when set.
The token is used for source checkout and Git delivery. A provider receives it only when the runtime configuration explicitly declares GH_TOKEN.
--repository <OWNER/NAME>
GitHub repository in owner/name form. Requires --target
--branch <BRANCH>
Source branch to resolve for the named run. Requires --target
--revision <SHA>
Exact source commit SHA. Requires --target
--submission-key <KEY>
Stable idempotency key for safely retrying submission
-d, --detach
Return after submission instead of following NDJSON run events
--validate-only
Validate and materialize the run without submitting it or contacting a target
--delivery <MODE>
Materialize this template-owned delivery mode
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template.
Named-target runs forward GH_TOKEN for the generated GitHub merge operation.
-h, --help
Print help (see a summary with '-h')
RUNTIME CONFIGURATION
The file is secret-free JSON. For example:
{
"harness": "codex",
"provider": "openrouter",
"size": "medium",
"nodes": {
"worker": {
"kind": "agent",
"model": "provider-model-id",
"connections": {"openrouter": ["OPENROUTER_API_KEY"]}
}
}
}
Provider choices are codex/openai, codex/openrouter, codex/bedrock, claude/anthropic,
claude/openrouter, and claude/bedrock. Known-incompatible harness/provider pairs are
codex/anthropic and claude/openai. Model IDs are passed unchanged to the selected harness and
provider; Zeroshot does not maintain or validate provider model catalogs.
Sizes are small, medium, and large.
Every executable graph node needs a same-named binding. Agent bindings require kind and model.
Optional fields are effort (low, medium, high, xhigh, or max when supported), sessionScope
(execution or node_instance), and connections. Each connection key maps to the exact
environment variable names required by that node; never put values in this file.
Use `zeroshot template show TEMPLATE` to inspect node names. With --pr or --ship, omit the
template-owned delivery binding.
--uniform-runtime-config requires harness, provider, and model. It accepts optional size,
effort, sessionScope, and connections fields without nodes. Zeroshot expands that agent binding
across every executable graph node and supplies graph-visible Git delivery bindings itself.
zeroshot list¶
List runs as JSON
Usage: zeroshot list [OPTIONS]
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
-h, --help
Print help
zeroshot status¶
Read a run's current status as JSON
Usage: zeroshot status [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
-h, --help
Print help
zeroshot watch¶
Follow a run's durable event stream as NDJSON
Usage: zeroshot watch [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
--after <CURSOR>
Resume strictly after this durable cursor
-h, --help
Print help
zeroshot logs¶
Follow a run's log stream as NDJSON
Usage: zeroshot logs [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
--after <CURSOR>
Resume strictly after this durable cursor
--execution <EXECUTION_REF>
Return records only for this opaque execution selector
-h, --help
Print help
zeroshot attach¶
Attach to an execution's interactive event stream as NDJSON
Usage: zeroshot attach [OPTIONS] <RUN_ID> <EXECUTION_REF>
Arguments:
<RUN_ID>
Public run ID
<EXECUTION_REF>
Execution reference emitted by the run
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
-h, --help
Print help
zeroshot force-stop¶
Force a run to stop and write the result as JSON
Usage: zeroshot force-stop [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
-h, --help
Print help
zeroshot version¶
zeroshot help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot help [COMMAND]
Commands:
target Manage named targets or serve a direct target
connection Inspect and manage named runtime connections
profile Manage reusable graph/runtime profiles
template Inspect built-in graph templates
plan Validate, submit, and observe hosted merge plans
run Submit a graph run locally or to a named target
list List runs as JSON
status Read a run's current status as JSON
watch Follow a run's durable event stream as NDJSON
logs Follow a run's log stream as NDJSON
attach Attach to an execution's interactive event stream as NDJSON
force-stop Force a run to stop and write the result as JSON
version Print the Zeroshot version
help Print this message or the help of the given subcommand(s)