Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coval.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 whenUse agent mode when
A human is exploring at a terminalA coding agent, script, or wrapper invokes the CLI
You want spinners, prompts, and colorYou need a stable contract for parsing
You want a pager or table viewYou 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

FieldDescription
aciOpen ACI version this envelope conforms to
oktrue on success, false on error
resource / operationThe command namespace and verb
summaryOne-line human-facing summary; safe to surface in chat UIs
dataOperation result. List operations return arrays; one operations return objects
warningsNon-fatal advisories the agent should consider before chaining
next_actionsSuggested follow-up commands with full argv ready to execute
errorPresent 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.