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.

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:

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

# 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:

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' },
          ],
        },
      },
    )
  },
})

# 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:

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:

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:

$ 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