> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wevm/incur/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Policy

> Control when command output is displayed to humans vs agents

Output policy controls whether output data is displayed to humans in TTY mode while still returning it to agents via `--json`, `--format`, or `--verbose`.

## Overview

By default, all command output is displayed to everyone (`'all'`). Set `outputPolicy: 'agent-only'` to suppress data output in human/TTY mode while still returning structured data to agents.

```ts theme={null}
cli.command('deploy', {
  outputPolicy: 'agent-only',
  run() {
    // Agents get the structured data; humans see nothing (or just CTAs/errors)
    return { id: 'deploy-123', url: 'https://staging.example.com' }
  },
})
```

## Use Cases

### Internal Commands

Commands designed for agent-only use that produce verbose machine-readable output:

```ts theme={null}
cli.command('sync', {
  outputPolicy: 'agent-only',
  run() {
    return {
      synced: true,
      files: 142,
      bytes: 8_432_123,
      checksum: 'a3f5e9c2...',
    }
  },
})
```

```sh theme={null}
# Human mode (TTY)
$ my-cli sync
# (no output)

# Agent mode (piped or --json)
$ my-cli sync --json
# → {"ok":true,"data":{"synced":true,"files":142,...}}
```

### Commands with Side Effects

Commands that perform actions but don't need to display data:

```ts theme={null}
cli.command('publish', {
  outputPolicy: 'agent-only',
  run(c) {
    return c.ok(
      { version: '1.2.3', published: true },
      {
        cta: {
          commands: [
            { command: 'status', description: 'View publication status' },
          ],
        },
      },
    )
  },
})
```

```sh theme={null}
# Human mode: sees CTAs but not the data
$ my-cli publish
# Next:
#   my-cli status – View publication status

# Agent mode: sees full output
$ my-cli publish --json
# → {"ok":true,"data":{"version":"1.2.3","published":true},...}
```

## Inheritance

Set `outputPolicy` on a group or root CLI to inherit across all children:

```ts theme={null}
const internal = Cli.create('internal', {
  description: 'Internal commands',
  outputPolicy: 'agent-only',
})

internal.command('sync', { run: () => ({ synced: true }) }) // inherits agent-only
internal.command('status', {
  outputPolicy: 'all', // overrides to show output
  run: () => ({ ok: true }),
})
```

## CLI-Level Policy

Set `outputPolicy` at the CLI level to apply to all commands by default:

```ts theme={null}
Cli.create('my-cli', {
  description: 'My CLI',
  outputPolicy: 'agent-only',
})
  .command('deploy', { run: () => ({ deployed: true }) }) // inherits agent-only
  .command('status', {
    outputPolicy: 'all', // override for this command
    run: () => ({ ok: true }),
  })
  .serve()
```

## Behavior Details

### Human Mode (TTY)

When `outputPolicy: 'agent-only'` and stdout is a TTY:

* **Data output is suppressed** — return value is not displayed
* **Errors are still shown** — `error()` calls display normally
* **CTAs are still shown** — `ok()` and `error()` CTAs display normally
* **`--json` overrides** — explicit format flags show data
* **`--verbose` overrides** — full envelope is shown

### Agent Mode (Non-TTY)

When stdout is not a TTY (piped, redirected, or consumed by an agent):

* **Data is always included** — regardless of `outputPolicy`
* **Full envelope format** — agents always see structured output

## Forcing Data Display

Humans can override `agent-only` with explicit format flags:

```sh theme={null}
$ my-cli deploy --json
# → {"ok":true,"data":{"id":"deploy-123",...}}

$ my-cli deploy --format yaml
# → ok: true
# → data:
# →   id: deploy-123
# →   url: https://staging.example.com

$ my-cli deploy --verbose
# → ok: true
# → data:
# →   id: deploy-123
# →   url: https://staging.example.com
# → meta:
# →   command: deploy
# →   duration: 3200ms
```

## Policy Values

| Value          | Description                                                                 |
| -------------- | --------------------------------------------------------------------------- |
| `'all'`        | Displays to both humans and agents (default)                                |
| `'agent-only'` | Suppresses data output in human/TTY mode while still returning it to agents |

## When to Use

Use `'agent-only'` for:

* Commands designed for agent orchestration
* Internal commands that produce verbose machine-readable output
* Commands where the side effect matters more than the return value
* Commands that use CTAs to guide users instead of showing raw data

Use `'all'` (default) for:

* Commands where the output is the primary value (queries, reports)
* Commands humans invoke directly
* Commands with concise, human-readable output