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¶
Enforce your team's QA process on coding agents: run the graph you define 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:
memory Initialize local Active Memory through the canonical skill
acp Serve one local Zeroshot profile as an experimental ACP agent over stdio
ui Serve the local profile editor and live or recorded run history
target Manage named targets or serve a direct target
delegation Manage user or organization machine delegations and API keys
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
update Update this executable and managed agent skills to the newest canonical release
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
resume Start a new attempt from a failed run's retained workspace or a saved checkpoint
checkpoints List one page of a run's saved workspace checkpoints as JSON
discard-workspace Permanently delete an abandoned retained target workspace
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 memory¶
Initialize local Active Memory through the canonical skill
Usage: zeroshot memory <COMMAND>
Commands:
init Initialize local Active Memory or resume its saved work
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
zeroshot memory init¶
Initialize local Active Memory or resume its saved work.
Creates a private session directory on the first call. Later calls return pending agent tasks, validate their responses, and publish after complete maintenance. The zeroshot-memory-init skill orchestrates the specialists using the host's connections. This command makes no model calls. It discovers all finished local runs and uses their recorded checkouts for current-source maintenance.
Usage: zeroshot memory init [OPTIONS] --directory <DIR>
Options:
--ignore-repos <REPO>...
Repositories to exclude by inventory alias: name, owner/repo, absolute path or repo ID. Comma-separated or repeated; saved with the session. Matching is exact and case-sensitive
--ignore-graphs <GRAPH>...
Graphs to exclude by exact authored root name or graph hash shown in the inventory. Comma-separated or repeated; saved with the session. Matching is exact and case-sensitive
--directory <DIR>
Private session directory outside repository checkouts; created if it does not exist
-h, --help
Print help (see a summary with '-h')
zeroshot memory help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot memory help [COMMAND]
Commands:
init Initialize local Active Memory or resume its saved work
help Print this message or the help of the given subcommand(s)
zeroshot acp¶
Serve one local Zeroshot profile as an experimental ACP agent over stdio.
The MVP supports one active session and text prompts. The profile must accept one task string and return one response string from every success node. It supports local Codex or Claude node-instance sessions, without maps, delivery, connections, MCP, or session reload.
Usage: zeroshot acp --profile <local:NAME>
Options:
--profile <local:NAME>
Local profile exposed by this agent process, in local:NAME form
-h, --help
Print help (see a summary with '-h')
zeroshot ui¶
Serve the local profile editor and live or recorded run history.
Open the printed /ui/ URL. Profiles always use the CLI's local store. Run history uses the local controller unless --target selects a configured target. Ctrl-C stops the UI server; active runs continue.
Usage: zeroshot ui [OPTIONS]
Options:
--listen <LISTEN>
Loopback address for the local UI
[default: 127.0.0.1:4173]
--target <NAME>
Read run history from this configured target. Profiles remain local
-h, --help
Print help (see a summary with '-h')
zeroshot target¶
Manage named targets or serve a direct target.
The built-in `platform` target points to https://api.cloud.zeroshot.sh. Run `zeroshot target login platform` to sign in. For unattended access, set ZEROSHOT_API_KEY instead of logging in. See https://cloud.zeroshot.sh/docs for Platform setup.
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.
Builds with UI support also serve the profile editor and run history at /ui/. The UI shares this listener and stores profiles under --storage.
Direct mode is unauthenticated. Bind or publish it only on trusted networks.
Usage: zeroshot target serve [OPTIONS] --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.
Must match the browser's origin, including the published port, when using the UI.
--storage <DIRECTORY>
Directory that stores target state, UI profiles, and run data
--operator-diagnostics-json
Write private operator diagnostics as JSON lines to stdout
-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 delegation¶
Manage user or organization machine delegations and API keys.
Requires human login. Set ZEROSHOT_API_KEY for unattended target commands; set ZEROSHOT_ORGANIZATION to select an organization with a user-owned key.
Usage: zeroshot delegation <COMMAND>
Commands:
list List delegation metadata without secret keys
create Create a delegation and its first API key. Prints the key once
show Read one delegation and its key metadata
disable Disable a delegation and revoke its access
key Create, inspect, or revoke a delegation's API keys
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
API keys act with their owner's current permissions and support every target command except delegation management. User-owned delegations follow the user's memberships; organization-owned delegations stay in one organization and require an owner or admin to manage. Keys expire after 90 days by default, with a maximum of 365 days. Creation prints the secret once. Store it in your CI secret store; do not put it in profiles, connections, or run input.
zeroshot delegation list¶
List delegation metadata without secret keys
Usage: zeroshot delegation list [OPTIONS]
Options:
--target <NAME>
Configured hosted target
[default: platform]
--owner <OWNER>
Delegate your user or an organization
[default: user]
[possible values: user, org]
--organization <UUID>
Organization UUID. Required with --owner org
-h, --help
Print help
zeroshot delegation create¶
Create a delegation and its first API key. Prints the key once
Usage: zeroshot delegation create [OPTIONS] <NAME>
Arguments:
<NAME>
Display name for this machine delegation
Options:
--target <NAME>
Configured hosted target
[default: platform]
--owner <OWNER>
Delegate your user or an organization
[default: user]
[possible values: user, org]
--organization <UUID>
Organization UUID. Required with --owner org
--expires-in-days <EXPIRES_IN_DAYS>
API key lifetime in days (1-365)
[default: 90]
-h, --help
Print help
zeroshot delegation show¶
Read one delegation and its key metadata
Usage: zeroshot delegation show [OPTIONS] <ID>
Arguments:
<ID>
Delegation UUID
Options:
--target <NAME>
Configured hosted target
[default: platform]
-h, --help
Print help
zeroshot delegation disable¶
Disable a delegation and revoke its access
Usage: zeroshot delegation disable [OPTIONS] <ID>
Arguments:
<ID>
Delegation UUID
Options:
--target <NAME>
Configured hosted target
[default: platform]
-h, --help
Print help
zeroshot delegation key¶
Create, inspect, or revoke a delegation's API keys
Usage: zeroshot delegation key <COMMAND>
Commands:
list List key metadata without secrets
create Create another key for overlapping rotation. Prints the key once
revoke Revoke one key. Accepted runs continue
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
zeroshot delegation key list¶
List key metadata without secrets
Usage: zeroshot delegation key list [OPTIONS] <ID>
Arguments:
<ID>
Delegation UUID
Options:
--target <NAME>
Configured hosted target
[default: platform]
-h, --help
Print help
zeroshot delegation key create¶
Create another key for overlapping rotation. Prints the key once
Usage: zeroshot delegation key create [OPTIONS] <ID>
Arguments:
<ID>
Delegation UUID
Options:
--target <NAME>
Configured hosted target
[default: platform]
--name <NAME>
Optional label for this key
--expires-in-days <EXPIRES_IN_DAYS>
API key lifetime in days (1-365)
[default: 90]
-h, --help
Print help
zeroshot delegation key revoke¶
Revoke one key. Accepted runs continue
Usage: zeroshot delegation key revoke [OPTIONS] <ID> <KEY_ID>
Arguments:
<ID>
Delegation UUID
<KEY_ID>
Key UUID
Options:
--target <NAME>
Configured hosted target
[default: platform]
-h, --help
Print help
zeroshot delegation key help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot delegation key help [COMMAND]
Commands:
list List key metadata without secrets
create Create another key for overlapping rotation. Prints the key once
revoke Revoke one key. Accepted runs continue
help Print this message or the help of the given subcommand(s)
zeroshot delegation help¶
Print this message or the help of the given subcommand(s)
Usage: zeroshot delegation help [COMMAND]
Commands:
list List delegation metadata without secret keys
create Create a delegation and its first API key. Prints the key once
show Read one delegation and its key metadata
disable Disable a delegation and revoke its access
key Create, inspect, or revoke a delegation's API keys
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>
Connection scope. Defaults to the authenticated owner's scope
[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>
Connection scope. Defaults to the authenticated owner's scope
[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>
Connection scope. Defaults to the authenticated owner's scope
[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>
Hosted profile scope. Defaults to the authenticated owner's scope
[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
- auto-research: Research with ten iterations by default and independent evidence gates
- issue-review: Inspect an issue proposal and post a review report
- pr-review: Review a PR diff, conditionally reproduce behavior, and post a concise report
--runtime-config <FILE>
--uniform-runtime-config <FILE>
--default
--delivery <MODE>
Template delivery mode. Defaults to pull_request for software-change, comment for issue-review and pr-review, otherwise none
--push
Commit and push the managed run branch without opening a pull request
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template
--no-pr-feedback
Do not route visible pull-request feedback through the autonomous repair loop
--target <NAME>
Use this named hosted target. If omitted, use local profiles
--scope <SCOPE>
Hosted profile scope. Defaults to the authenticated owner's scope
[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>
Hosted profile scope. Defaults to the authenticated owner's scope
[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>
Hosted profile scope. Defaults to the authenticated owner's scope
[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>
Hosted profile scope. Defaults to the authenticated owner's scope
[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
- auto-research: Research with ten iterations by default and independent evidence gates
- issue-review: Inspect an issue proposal and post a review report
- pr-review: Review a PR diff, conditionally reproduce behavior, and post a concise report
Options:
--delivery <MODE>
Template delivery mode. Defaults to pull_request for software-change, comment for issue-review and pr-review, otherwise none
--push
Commit and push the managed run branch without opening a pull request
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template
--no-pr-feedback
Do not route visible pull-request feedback through the autonomous repair loop
-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 current Git merge delivery 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.
Platform assigns every run ID atomically at submission. After a node's dependencies succeed, Platform
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.
Local runs use --cwd or the invoking folder; Git worktrees use their root. Local Git delivery requires an attached, committed branch and an HTTPS/SSH remote. PR/merge also require a supported forge. Named targets require a committed Git source. Local workspaces must not overlap Zeroshot state. For local PR and merge delivery, the target is the branch's upstream when configured, otherwise the local branch name. Preparation verifies that the remote contains the target before agents start. To target `main` from a fresh worktree, run `git branch --set-upstream-to=origin/main`, or create the worktree from `origin/main`.
A foreground run follows NDJSON events until completion. --detach returns after submission. Ctrl-C before the submission attempt begins cancels the command; once it begins, Ctrl-C waits for the receipt and then detaches. During observation, Ctrl-C detaches without stopping the run.
Usage: zeroshot run [OPTIONS] --title <TITLE>
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
- auto-research: Research with ten iterations by default and independent evidence gates
- issue-review: Inspect an issue proposal and post a review report
- pr-review: Review a PR diff, conditionally reproduce behavior, and post a concise report
--input <FILE>
Load the graph's initial input from this JSON file
--task-from <URL>
Resolve a GitHub issue or pull-request URL into review input before starting
--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
--environment <FILE>
Load a JSON environment definition: setup, startup, public variables, and hook connections
--no-environment
Send an empty environment ({}) to bypass the target's configured default
--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
--cwd <FOLDER>
Working folder (default: invoking folder). File arguments stay relative to the invoking folder
--source-connection <KEY>
Named connection for Git checkout and push.
HTTPS uses GIT_USERNAME and GIT_PASSWORD; SSH uses GIT_SSH_PRIVATE_KEY and GIT_SSH_KNOWN_HOSTS.
--repository <REPOSITORY>
Repository in GitHub owner/name form or a credential-free HTTPS/SSH Git URL. 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 running preparation scripts.
Remote profiles still require target access. This does not check dependency installation or connection availability.
--delivery <MODE>
Template delivery mode. Defaults to pull_request for software-change, comment for issue-review and pr-review, otherwise none
--push
Commit and push the managed run branch without opening a pull request
--pr
Materialize pull-request delivery for the software-change template
--ship
Materialize merge delivery for the software-change template
--no-pr-feedback
Do not route visible pull-request feedback through the autonomous repair loop
-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, claude/bedrock, codex/gateway, claude/gateway, copilot/github,
pi/anthropic, pi/openai, pi/openrouter, pi/bedrock, and pi/gateway. Gateway connections
require GATEWAY_BASE_URL and GATEWAY_API_KEY. Codex uses Responses and Claude uses Messages.
The pi/gateway lane also carries GATEWAY_API, which names the wire protocol as one of
openai-responses, openai-completions, or anthropic-messages.
Declaring ANTHROPIC_BASE_URL with ANTHROPIC_API_KEY sends the pi/anthropic lane to a
caller-owned Anthropic Messages endpoint.
Known-incompatible harness/provider pairs include
codex/anthropic, claude/openai, and pi/github. Local Copilot reuses its native user login;
contained
Copilot uses a user-backed GitHub connection with COPILOT_GITHUB_TOKEN. Pi has no permission
control of its own, so its contained runs rely on the disposable capsule rather than a bypass
argument. 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.
The run-level harness and provider are the default lane. An agent binding may add
"lane": {"harness": "claude", "provider": "anthropic"} to run that node on another accepted
pair; git_delivery and comment_delivery bindings cannot. --uniform-runtime-config applies one lane to every agent
node. Named targets must advertise per-node lane support (openengine.node-runtime-lanes/v1), and
a local run first checks that each lane's executable (codex, claude, or copilot) is on PATH.
Use `zeroshot template show TEMPLATE` to inspect node names. With --push, --pr, or --ship, omit the
template-owned delivery binding.
--uniform-runtime-config requires harness, provider, and model. It accepts optional size,
effort, sessionScope, connections, activeMemory, and globalAgents fields without nodes.
Zeroshot expands that agent binding
across every executable graph node and supplies graph-visible Git delivery bindings itself.
Omitted connections reuse native local login for codex/openai, claude/anthropic,
copilot/github, pi/anthropic, and pi/openai; other local lanes and contained targets derive
their canonical connection requirements.
ENVIRONMENT PREPARATION
For Docker or Platform targets, pass --environment environment.json with a separate, flat JSON
definition (not a profile field or an "environment" wrapper):
{
"setup": "apt-get update && apt-get install -y jq",
"startup": "npm ci",
"variables": {"CI": "true"}
}
Setup runs as root before checkout or workspace restore. Startup runs as the non-root
workspace owner in the checkout before any agent starts. Workers and reviewers share the
prepared workspace. Both hooks rerun on resume; startup must tolerate existing files.
Install OS packages in setup, project dependencies in startup, and shared executable tools
under $ZEROSHOT_TOOLS/bin (already on every hook and agent's PATH). Shell exports last only
for that hook; use variables for public values shared with agents. Scripts and variables
are public. If hooks need secrets, add e.g. "connections": {"package-registry": ["NPM_TOKEN"]}.
Hook connections are separate from node connections.
Hook failures stop the run before agents start and use no graph retry attempts.
Inspect `zeroshot logs RUN_ID --target NAME` for preparation output.
Omit both flags to allow host defaults; direct Docker defaults to the base environment.
--no-environment sends {} to bypass host defaults. Local runs use the invoking machine and
reject hooks and hook connections.
Installation, services, limits, and recovery:
https://the-open-engine.github.io/zeroshot/current/guides/runtime-environments/
zeroshot update¶
Update this executable and managed agent skills to the newest canonical release.
Downloads the declared archive and agent skills from the latest GitHub Release, verifies their SHA256SUMS entries and the executable version, then replaces this executable and any unchanged Zeroshot-managed skill copies. User-edited skills are preserved and reported as conflicts. The executable's directory must be writable; Zeroshot does not elevate privileges.
Usage: zeroshot update
Options:
-h, --help
Print help (see a summary with '-h')
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 resume¶
Start a new attempt from a failed run's retained workspace or a saved checkpoint.
By default, restart the original graph using its latest retained workspace. Use --from-checkpoint to continue from a checkpoint listed by `zeroshot checkpoints`. The successor resolves its original connection requirements again; make those credentials available.
Target runs reuse the saved environment definition: setup runs before workspace restore, then startup runs before the graph. Startup must tolerate existing workspace files. Services, Docker state, and agent conversations are not restored.
Usage: zeroshot resume [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
--from-checkpoint <ID>
Restore this checkpoint and continue from its saved graph boundary
-h, --help
Print help (see a summary with '-h')
zeroshot checkpoints¶
List one page of a run's saved workspace checkpoints as JSON.
Each entry restores the workspace and graph state before its named node or outer parallel/map group. Select its checkpointId with `zeroshot resume RUN_ID --from-checkpoint ID`. When nextAfter is present, pass it as --after to fetch the next page.
Usage: zeroshot checkpoints [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Public run ID
Options:
--target <NAME>
Use this named target. If omitted, use the local controller
--after <ID>
List checkpoints strictly after this checkpoint ID
--limit <COUNT>
Maximum checkpoints to return, from 1 to 100. Defaults to 50
-h, --help
Print help (see a summary with '-h')
zeroshot discard-workspace¶
Permanently delete an abandoned retained target workspace
Usage: zeroshot discard-workspace [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:
memory Initialize local Active Memory through the canonical skill
acp Serve one local Zeroshot profile as an experimental ACP agent over stdio
ui Serve the local profile editor and live or recorded run history
target Manage named targets or serve a direct target
delegation Manage user or organization machine delegations and API keys
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
update Update this executable and managed agent skills to the newest canonical release
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
resume Start a new attempt from a failed run's retained workspace or a saved checkpoint
checkpoints List one page of a run's saved workspace checkpoints as JSON
discard-workspace Permanently delete an abandoned retained target workspace
version Print the Zeroshot version
help Print this message or the help of the given subcommand(s)