# CLI Reference

Commands, flags, and command groups generated from the current Cobra CLI source.

Source: https://agentclash.dev/docs/reference/cli
Markdown export: https://agentclash.dev/docs-md/reference/cli

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`