CLI Reference

This page is generated from the Cobra command definitions in cli/cmd.

Global flags

• --api-url — API base URL (overrides config)
• --json — Output in JSON format
• --no-color — Disable color output
• --output (-o) — Output format: table, json, yaml
• --quiet (-q) — Suppress non-essential output
• --verbose (-v) — Enable debug output on stderr
• --workspace (-w) — Workspace ID (overrides config)
• --yes — Skip confirmation prompts

Command groups

artifact

Upload and download artifacts

download <artifactId>

Download an artifact

Flags

• --output (-O) — Output file path (defaults to stdout)

upload <file>

Upload an artifact

Flags

• --metadata — JSON metadata (optional)
• --run — Run ID (optional)
• --run-agent — Run agent ID (optional)
• --type (required) — Artifact type (required)

auth

Manage authentication

login

Log in to AgentClash

Flags

• --device — Print the verification URL instead of opening the browser automatically
• --force — Start a new browser login even if existing credentials are valid

logout

Log out and remove stored credentials

status

Show current authentication status

tokens

Manage CLI access tokens

list

List your CLI tokens

revoke <token-id>

Revoke a CLI token

build

Manage agent builds

create

Create a new agent build

Flags

• --description — Build description
• --name (required) — Build name (required)

get <id>

Get agent build with version history

list

List agent builds

version

Manage agent build versions

create <buildId>

Create a new draft version

Flags

• --agent-kind — Agent kind: llm_agent, workflow_agent, programmatic_agent, multi_agent_system, hosted_external
• --spec-file — JSON file with version spec fields

get <versionId>

Get a build version

ready <versionId>

Mark a version as ready (immutable, deployable)

update <versionId>

Update a draft build version

Flags

• --spec-file — JSON file with updated version spec fields

validate <versionId>

Validate a build version

challenge-pack

Manage challenge packs

list

List challenge packs

publish <file>

Publish a challenge pack YAML bundle

validate <file>

Validate a challenge pack YAML bundle

compare

Compare runs and evaluate release gates

gate

Evaluate a release gate (nonzero exit = regression or missing evidence)

Flags

• --baseline (required) — Baseline run ID (required)
• --candidate (required) — Candidate run ID (required)

runs

Compare baseline vs candidate runs

Flags

• --baseline (required) — Baseline run ID (required)
• --baseline-agent — Baseline run agent ID (optional)
• --candidate (required) — Candidate run ID (required)
• --candidate-agent — Candidate run agent ID (optional)

config

Manage CLI configuration

get <key>

Get a config value

list

List all config values

set <key> <value>

Set a config value

deployment

Manage agent deployments

create

Create an agent deployment

Flags

• --agent-build-id — Agent build ID
• --build-version-id — Agent build version ID
• --from-file — JSON file with deployment spec
• --model-alias-id — Model alias ID
• --name — Deployment name
• --provider-account-id — Provider account ID
• --runtime-profile-id — Runtime profile ID

list

List agent deployments

infra

Manage infrastructure resources

model-catalog

Browse the global model catalog

get <id>

Get a model catalog entry

list

List available models

init

Initialize a project with .agentclash.yaml

Flags

• --org-id — Organization ID to bind
• --workspace-id — Workspace ID to bind

org

Manage organizations

create

Create a new organization

Flags

• --name (required) — Organization name (required)
• --slug — Organization slug (optional, auto-generated)

get <id>

Get organization details

list

List organizations you belong to

members

Manage organization members

invite <orgId>

Invite a member to the organization

Flags

• --email (required) — Email address to invite (required)
• --role default: org_member — Role: org_admin, org_member

list <orgId>

List organization members

update <membershipId>

Update an organization membership

Flags

• --role — New role: org_admin, org_member
• --status — New status: active, suspended, archived

update <id>

Update an organization

Flags

• --name — New organization name
• --status — New status (active, archived)

playground

Manage playgrounds, test cases, and experiments

create

Create a playground

Flags

• --from-file — JSON file with playground spec
• --name — Playground name

delete <id>

Delete a playground

experiment

Manage playground experiments

batch <playgroundId>

Create experiments in batch (one per model)

Flags

• --from-file — JSON file with batch experiment spec

compare

Compare two experiments

Flags

• --baseline (required) — Baseline experiment ID (required)
• --candidate (required) — Candidate experiment ID (required)

create <playgroundId>

Create an experiment

Flags

• --from-file — JSON file with experiment spec

get <experimentId>

Get an experiment

list <playgroundId>

List experiments

results <experimentId>

List results for an experiment

get <id>

Get a playground

list

List playgrounds

test-case

Manage playground test cases

create <playgroundId>

Create a test case

Flags

• --from-file — JSON file with test case spec

delete <testCaseId>

Delete a test case

list <playgroundId>

List test cases

update <testCaseId>

Update a test case

Flags

• --from-file — JSON file with test case spec

update <id>

Update a playground

Flags

• --from-file — JSON file with playground spec

replay

View execution replays

get <runAgentId>

Get execution replay steps

Flags

• --cursor — Step offset to start from
• --limit — Steps per page (1-200)

run

Manage evaluation runs

agents <runId>

List agents in a run

create

Create and submit an evaluation run

Flags

• --challenge-pack-version — Challenge pack version ID (optional in a TTY; prompted when omitted)
• --deployments — Agent deployment IDs (optional in a TTY; prompted when omitted)
• --follow — Follow run events after creation
• --input-set — Challenge input set ID (optional)
• --name — Run name (optional)

events <runId>

Stream live run events via SSE

get <id>

Get run details

list

List runs in the workspace

ranking <runId>

Get run ranking and composite scores

Flags

• --sort-by — Sort by: composite, correctness, reliability, latency, cost

scorecard <runAgentId>

Get agent scorecard

secret

Manage workspace secrets

delete <key>

Delete a secret

list

List workspace secret keys

set <key>

Create or update a secret

Flags

• --value — Secret value (reads from stdin if omitted)

version

Show CLI version information

workspace

Manage workspaces

create

Create a workspace

Flags

• --name (required) — Workspace name (required)
• --org — Organization ID (required)
• --slug — Workspace slug (optional)

get <id>

Get workspace details

list

List workspaces in an organization

Flags

• --org — Organization ID (uses default if not set)

members

Manage workspace members

invite

Invite a member to the workspace

Flags

• --email (required) — Email address to invite (required)
• --role default: workspace_member — Role: workspace_admin, workspace_member, workspace_viewer

list

List workspace members

update <membershipId>

Update a workspace membership

Flags

• --role — New role
• --status — New status

update <id>

Update a workspace

Flags

• --name — New workspace name
• --status — New status (active, archived)

use <id>

Set the default workspace

Source pointers

• cli/cmd/root.go
• cli/cmd/auth.go
• cli/cmd/workspace.go
• cli/cmd/run.go
• cli/cmd/compare.go