CLI reference

The agntz CLI ships inside @agntz/sdk. It creates YAML manifests, runs agents locally, and manages hosted runs and traces from the terminal.

# Run without installing
npx @agntz/sdk --help

# Or install globally
npm i -g @agntz/sdk
agntz --help

For the first local workflow, start with CLI getting started.

Command map

Every command supports terminal help:

agntz create --help
agntz run --help
agntz login --help
agntz runs --help
agntz traces --help

Auth and configuration

Hosted commands read credentials in this order:

1. AGNTZ_API_KEY
2. ~/.agntz/config.json, written by agntz login

API URL resolution uses:

1. command --url where supported
2. AGNTZ_API_URL
3. saved config
4. https://api.agntz.co

Local runs do not require an agntz API key. They use provider keys from your process environment, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or other keys required by the manifest's model/tool configuration.

create

agntz create "<description>" [options]

Generates a YAML manifest by calling the hosted agent-builder. No login is required.

Examples:

agntz create "Answer support questions in a concise tone" -o ./agents/support.yaml

agntz create "Add an HTTP order lookup tool" \
  --current-manifest ./agents/support.yaml \
  -o ./agents/support.yaml

agntz create "Classify inbound leads by urgency" --stdout > ./agents/lead-classifier.yaml

create validates that the builder returned YAML, parses the manifest to get its id, creates parent directories as needed, and prints the local run command to try next.

run

agntz run <path-or-id> [options] [input...]

Runs an agent. The target determines local vs hosted mode unless you force a mode.

Input resolution:

--input value > trailing positional text > piped stdin > empty string

Examples:

# Local file
agntz run ./agents/support.yaml --input "How do I reset my password?"

# Local file with stdin
cat ticket.txt | agntz run ./agents/support.yaml

# Local file with persistent conversation state
agntz run ./agents/support.yaml --session user-42 --input "My email changed"

# Hosted agent id
agntz run support --input "Hello" --remote

# Stream hosted or local output
agntz run ./agents/support.yaml --input "Walk me through this" --stream

Local runtime boundary: agntz run ./agents/support.yaml constructs a local SDK client with agntz({ agents: "<manifest-dir>" }). It can run agents whose requirements are satisfied by YAML plus environment configuration. If the agent declares local tools or resource providers that need application code, call @agntz/sdk from your service and pass tools / resources there.

login, logout, and whoami

agntz login --key <apiKey> [--url <apiUrl>]
agntz logout
agntz whoami

login writes credentials to ~/.agntz/config.json with owner-only permissions. logout removes that file. whoami prints the resolved API URL and a masked key source.

Examples:

agntz login --key ar_live_...
agntz login --key ar_live_... --url https://agntz-worker.example.com
AGNTZ_API_KEY=ar_live_... agntz whoami
agntz logout

Browser-based login is not implemented in the current CLI. Paste an API key from the hosted or self-hosted dashboard.

runs

Hosted run management. Requires AGNTZ_API_KEY or agntz login. Output is JSON.

agntz runs list   [--agent <id>] [--status <s>] [--limit <n>] [--cursor <c>]
agntz runs get    <runId>
agntz runs stream <runId> [--since <seq>]
agntz runs cancel <runId>

Examples:

agntz runs list --agent support --limit 20
agntz runs get run_123
agntz runs stream run_123 --since 10
agntz runs cancel run_123

runs stream emits the multiplexed event stream for a hosted run subtree. --since <seq> resumes from a sequence number.

traces

Hosted trace management. Requires AGNTZ_API_KEY or agntz login.

agntz traces list   [--agent <id>] [--status <s>] [--limit <n>] [--cursor <c>]
agntz traces get    <traceId>
agntz traces delete <traceId>

Examples:

agntz traces list --agent support --status failed --limit 10
agntz traces get trace_123
agntz traces delete trace_123

Current CLI boundary

The current CLI command surface is intentionally small:

create, run, login, logout, whoami, runs, traces

The current CLI does not provide project scaffolding, eval execution, validation-only execution, an interactive playground, or a Studio launcher. Use the SDK docs for in-process validation/runtime wiring, and use the hosted app for managed agent editing.

Exit behavior

The CLI writes human-readable errors to stderr. For structured programmatic integration, use @agntz/sdk for local execution or @agntz/client for hosted execution.