Agent Mode

Coval’s agent mode implements Open ACI, an open draft specification (v0.1) for agent-native command-line interfaces. The Coval CLI is its reference implementation.

Agent mode is a global behavior toggled with --agent. It turns every command into a non-interactive call that returns a stable JSON envelope, suppresses prompts and progress UI, and emits suggested next actions for an orchestrating agent to chain on.

When to use it

Use ordinary mode when	Use agent mode when
A human is exploring at a terminal	A coding agent, script, or wrapper invokes the CLI
You want spinners, prompts, and color	You need a stable contract for parsing
You want a pager or table view	You want structured errors and next-action hints

Quick start

# Discover what the CLI can do
coval --agent agent doctor
coval --agent agent manifest

# Inspect a resource surface
coval --agent runs context

# Launch a run with structured input
coval --agent runs launch --input-json @run.json

The envelope

Every agent-mode response — success or failure — returns the same top-level envelope.

Success

{
  "aci": "0.1",
  "ok": true,
  "resource": "runs",
  "operation": "launch",
  "summary": "Run run_123 was queued.",
  "data": {
    "id": "run_123",
    "status": "queued"
  },
  "warnings": [],
  "next_actions": [
    {
      "id": "watch",
      "label": "Watch run",
      "argv": ["coval", "--agent", "runs", "watch", "run_123"],
      "safe": true,
      "primary": true,
      "requires_confirmation": false
    }
  ]
}

Error

{
  "aci": "0.1",
  "ok": false,
  "resource": "runs",
  "operation": "launch",
  "error": {
    "code": "invalid_input",
    "message": "test_set_id is required",
    "field": "test_set_id"
  },
  "warnings": [],
  "next_actions": []
}

Field reference

Field	Description
`aci`	Open ACI version this envelope conforms to
`ok`	`true` on success, `false` on error
`resource` / `operation`	The command namespace and verb
`summary`	One-line human-facing summary; safe to surface in chat UIs
`data`	Operation result. List operations return arrays; one operations return objects
`warnings`	Non-fatal advisories the agent should consider before chaining
`next_actions`	Suggested follow-up commands with full `argv` ready to execute
`error`	Present only when `ok` is `false`

Agent mode takes precedence over --format json and disables interactive prompts, progress bars, audio downloads, and not-found hints that would otherwise write to stderr.

Discovery

Two commands let an agent introspect the CLI without prior knowledge of its surface.

`agent doctor`

Reports whether the CLI is installed, authenticated, and able to reach the API. Run this first when bootstrapping.

coval --agent agent doctor

`agent manifest`

Returns the full set of resources, operations, supported profiles (structured input, next actions, skills), and help_argv pointers. Agents should call this once per session and rely on --help for exhaustive flag detail rather than caching command shapes.

coval --agent agent manifest

Resource context

Every resource exposes a context subcommand that describes its operations, required fields, and primary next actions — without making a network call or requiring auth.

coval --agent runs context
coval --agent agents context
coval --agent test-sets context

Use context to plan a chain of calls before executing any of them.

Structured input with `--input-json`

Body-bearing commands (create, update, launch, submit) accept structured input via --input-json. Explicit CLI flags overlay the JSON, so agents can pass a base payload and override individual fields.

# Inline JSON
coval --agent runs launch --input-json '{"agent_id":"a_1","test_set_id":"ts_1"}'

# From a file
coval --agent runs launch --input-json @run.json

# From stdin
cat run.json | coval --agent runs launch --input-json -

# JSON + flag override (flag wins)
coval --agent runs launch \
  --input-json @run.json \
  --persona-id persona_override

Invalid JSON in agent mode returns a structured invalid_input error rather than a free-text parse message.

Agent skills

agent skills lets an agent enumerate and install local skill bundles. By design there is no embedded catalog and no hardcoded remote source — agents must clone or pin a skills repo locally and point at it explicitly.

# List skills available in a local source directory
coval --agent agent skills list --source ./path/to/skills

# Install a skill into a local destination
coval --agent agent skills install <skill-id> \
  --source ./path/to/skills \
  --dest ./.agent-skills

Equivalent environment variables: COVAL_SKILLS_SOURCE, COVAL_SKILLS_DEST. Remote sources (URLs) are rejected with a structured error directing the agent to clone and pin the skill repository locally. Skill IDs containing path traversal are rejected before any filesystem access.

Safety model

next_actions carry a safe boolean and a requires_confirmation flag. Mutating actions (skill installs, runs launch, etc.) are marked accordingly so an orchestrator can gate them.
Agent mode never prompts. A command that would prompt in human mode returns an error envelope in agent mode.
Stdout is the envelope only. Diagnostic chatter that humans see (progress, hints, audio paths) is suppressed.

Getting Started

Resources

When to use it

Quick start

The envelope

Success

Error

Field reference

Discovery

`agent doctor`

`agent manifest`

Resource context

Structured input with `--input-json`

Agent skills

Safety model

​When to use it

​Quick start

​The envelope

​Success

​Error

​Field reference

​Discovery

​agent doctor

​agent manifest

​Resource context

​Structured input with --input-json

​Agent skills

​Safety model

When to use it

Quick start

The envelope

Success

Error

Field reference

Discovery

`agent doctor`

`agent manifest`

Resource context

Structured input with `--input-json`

Agent skills

Safety model