zeroshot-rust CLI reference

This reference is generated from the typed Clap command model and its Rust doc comments. Regenerate it with cargo run -p zeroshot-rust --example generate_cli_docs -- --write.

zeroshot-rust

Run multi-agent graph workloads locally or on named Zeroshot targets.

Single-result commands write JSON. Foreground `run`, `watch`, `logs`, and `attach` stream newline-delimited JSON (NDJSON).

Usage: zeroshot-rust [COMMAND]

Commands:
  target      Manage named targets or serve a direct target
  connection  Manage static credentials by connection key
  profile     Manage reusable graph/runtime profiles
  template    Inspect built-in graph templates
  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 Rust version
  help        Print this message or the help of the given subcommand(s)

Options:
  -V, --version
          Print the Zeroshot Rust version

  -h, --help
          Print help (see a summary with '-h')

zeroshot-rust target

Manage named targets or serve a direct target

Usage: zeroshot-rust target <COMMAND>

Commands:
  add    Register a named target
  login  Authenticate with a hosted named target
  setup  Configure the local profile for a named target
  serve  Serve a native-v2 target, unauthenticated unless --bootstrap-key-file is set
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

zeroshot-rust target add

Register a named target

Usage: zeroshot-rust 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-rust 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_RUST_CREDENTIAL_STORE to auto, system, or file to override automatic selection.

Usage: zeroshot-rust target login <NAME>

Arguments:
  <NAME>
          Local target name

Options:
  -h, --help
          Print help (see a summary with '-h')

zeroshot-rust target setup

Configure the local profile for a named target.

This changes only the local named-target registry; it does not configure the remote target.

Usage: zeroshot-rust target setup [OPTIONS] --repository <OWNER/NAME> <NAME>

Arguments:
  <NAME>
          Local target name

Options:
      --repository <OWNER/NAME>
          GitHub repository in owner/name form

      --branch <BRANCH>
          Default source branch used when a run does not specify --branch

  -h, --help
          Print help (see a summary with '-h')

zeroshot-rust target serve

Serve a native-v2 target, unauthenticated unless --bootstrap-key-file is set.

Without --bootstrap-key-file, clients connect directly with no authentication. With a bootstrap key, the server enables private authenticated access and consumes and removes the key file while starting.

Usage: zeroshot-rust 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

      --storage <DIRECTORY>
          Directory that stores target state and run data

      --bootstrap-key-file <PATH>
          Enable private auth with a one-time key file consumed and removed at startup.

          The target consumes and removes this file while starting. If omitted, the target accepts unauthenticated direct connections.

  -h, --help
          Print help (see a summary with '-h')

zeroshot-rust target help

Print this message or the help of the given subcommand(s)

Usage: zeroshot-rust target help [COMMAND]

Commands:
  add    Register a named target
  login  Authenticate with a hosted named target
  setup  Configure the local profile for a named target
  serve  Serve a native-v2 target, unauthenticated unless --bootstrap-key-file is set
  help   Print this message or the help of the given subcommand(s)

zeroshot-rust connection

Manage static credentials by connection key

Usage: zeroshot-rust 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

zeroshot-rust connection list

List connection metadata without secret values

Usage: zeroshot-rust 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-rust connection set

Create or replace one static connection

Usage: zeroshot-rust 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

zeroshot-rust connection delete

Delete one connection

Usage: zeroshot-rust 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-rust connection help

Print this message or the help of the given subcommand(s)

Usage: zeroshot-rust 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-rust profile

Manage reusable graph/runtime profiles

Usage: zeroshot-rust 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-rust profile list

List profile metadata

Usage: zeroshot-rust 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-rust profile set

Create or replace a fully materialized profile

Usage: zeroshot-rust 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 Rust-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-rust profile show

Show one profile with its graph and runtime

Usage: zeroshot-rust 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-rust profile remove

Remove one profile

Usage: zeroshot-rust 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-rust profile default

Set the scope's default profile, or clear it when NAME is omitted

Usage: zeroshot-rust 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-rust profile help

Print this message or the help of the given subcommand(s)

Usage: zeroshot-rust 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-rust template

Inspect built-in graph templates

Usage: zeroshot-rust 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-rust template list

List built-in template names as JSON

Usage: zeroshot-rust template list

Options:
  -h, --help
          Print help

zeroshot-rust template show

Write a built-in graph template as JSON

Usage: zeroshot-rust 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 Rust-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-rust template help

Print this message or the help of the given subcommand(s)

Usage: zeroshot-rust 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-rust 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-rust 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.

      --branch <BRANCH>
          Source branch to resolve on the named target. 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 Rust-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"]}
          }
        }
      }

    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-rust 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. Rust expands that agent binding
    across every executable graph node and supplies graph-visible Git delivery bindings itself.

zeroshot-rust list

List runs as JSON

Usage: zeroshot-rust list [OPTIONS]

Options:
      --target <NAME>
          Use this named target. If omitted, use the local controller

  -h, --help
          Print help

zeroshot-rust status

Read a run's current status as JSON

Usage: zeroshot-rust 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-rust watch

Follow a run's durable event stream as NDJSON

Usage: zeroshot-rust 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-rust logs

Follow a run's log stream as NDJSON

Usage: zeroshot-rust 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-rust attach

Attach to an execution's interactive event stream as NDJSON

Usage: zeroshot-rust 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-rust force-stop

Force a run to stop and write the result as JSON

Usage: zeroshot-rust 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-rust version

Print the Zeroshot Rust version

Usage: zeroshot-rust version

Options:
  -h, --help
          Print help

zeroshot-rust help

Print this message or the help of the given subcommand(s)

Usage: zeroshot-rust help [COMMAND]

Commands:
  target      Manage named targets or serve a direct target
  connection  Manage static credentials by connection key
  profile     Manage reusable graph/runtime profiles
  template    Inspect built-in graph templates
  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 Rust version
  help        Print this message or the help of the given subcommand(s)