> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Mode

> Run the Coval CLI from autonomous agents with structured I/O, discovery, and next actions

<Note>
  Coval's agent mode implements [Open ACI](https://github.com/lorenjphillips/open-aci), an open draft specification (v0.1) for agent-native command-line interfaces. The Coval CLI is its reference implementation.
</Note>

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

```bash theme={null}
# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.