> Note: `agent` is not currently published in the cmdhub registry. These docs are available by direct URL for development/reference use.

# Agent CLI

Schema-aware transforms between one command contract and another.

## Install

```bash
cmdhub get agent
```

## Authentication

Model profile

## Agent-Readable Catalog

- Machine-readable command catalog: `/cli/agent/catalog.json`
- Stable command anchors use the `cmd-...` IDs listed under each command.
- Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support.

## Overview

```bash
# Adapt a Gmail message into a calendar-event input contract
gmail message list --label INBOX --limit 1 --jsonl \
  | agent adapt --to "gcal event create"
```

## CLI Overview

Agent CLI for cross-app compilation and intent resolution

Agent compiles structured records from one cmdhub contract into another.

Common flows:
  gmail message get m1 --jsonl | agent explain --to intent.task.v1
  gmail message get m1 --jsonl | agent adapt --to intent.task.v1 --json
  gmail message get m1 --jsonl | agent adapt --to 'gcal event create' --dry-run
  agent schema --to 'gcal event create' --in

## Generated Coverage

- Command groups: `12`
- Total documented command nodes: `23`
- Live examples: `3`
- Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version`
- Machine-readable output: `--json`, `--jsonl`
- Human views: `summary`, `full`

## Auth Contract

- Auth mode: Model profile
- Provider permission model: local model profile
- Auth scopes: `local model/profile configuration`
- Scope note: Provider credentials stay with the source and destination CLIs.
- Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami`
- `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`.
- `auth whoami --json` is the stable way to answer identity questions.

## Agent Safety Notes

- Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first.
- Treat commands marked as mutating as state-changing local or provider operations.
- Mutating command paths: `agent auth login`, `agent auth logout`, `agent auth refresh`, `agent login`, `agent logout`, `agent model add`, `agent model remove`, `agent model use`
- Commands with `--dry-run`: `agent adapt`

## Global Flags

- `--json` (bool): Emit JSON machine output
- `--jsonl` (bool): Emit JSONL records for piping
- `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl
- `--view` (string): View mode: summary|full Default: `summary`.
- `--profile` (string): Config/auth profile
- `--config` (string): Config path override
- `--quiet` (bool): Suppress non-essential diagnostics
- `--debug` (bool): Enable debug diagnostics
- `--limit` (int): Maximum items to emit Default: `50`.
- `--page-size` (int): Requested upstream page size Default: `50`.
- `--cursor` (string): Continuation cursor
- `--no-paginate` (bool): Fetch only one page
- `--version` (bool): Print version information

## Command Reference

### `agent adapt`

- Anchor: `cmd-agent-adapt`
- Mutates state: `no`
- Supports dry run: `yes`

Compile one typed stream into another

Example:

```bash
agent adapt --help
gmail message get m1 --jsonl | agent adapt --to 'gcal event create' --dry-run
gmail message get m1 --jsonl | agent adapt --to 'gcal event create' --via intent.meeting_request.v1 --json
gmail message get m1 --jsonl | agent adapt --to intent.task.v1
```

Flags:

- `--dry-run` (bool): Dry run mode
- `--model` (string): Model profile name
- `--to` (string): Target command
- `--via` (string): Optional intermediate intent schema

### `agent auth`

- Anchor: `cmd-agent-auth`
- Mutates state: `no`
- Supports dry run: `no`

Show local agent auth state

The agent CLI does not own provider credentials. Provider CLIs such as gmail, gcal, gdrive, msdrive, mscal, slack, and notion handle their own auth. Configure model backends with agent model.

#### `agent auth login`

- Anchor: `cmd-agent-auth-login`
- Mutates state: `yes`
- Supports dry run: `no`

No-op for local agent auth

Example:

```bash
agent auth login
```

#### `agent auth logout`

- Anchor: `cmd-agent-auth-logout`
- Mutates state: `yes`
- Supports dry run: `no`

No-op for local agent auth logout

Example:

```bash
agent auth logout
agent auth logout --help
```

#### `agent auth refresh`

- Anchor: `cmd-agent-auth-refresh`
- Mutates state: `yes`
- Supports dry run: `no`

No-op for local agent auth refresh

Example:

```bash
agent auth refresh
```

#### `agent auth status`

- Anchor: `cmd-agent-auth-status`
- Mutates state: `no`
- Supports dry run: `no`

Show local agent auth status

Example:

```bash
agent auth status
agent auth status --json
```

#### `agent auth whoami`

- Anchor: `cmd-agent-auth-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Show local agent model profile identity

Example:

```bash
agent auth whoami
```

### `agent capabilities`

- Anchor: `cmd-agent-capabilities`
- Mutates state: `no`
- Supports dry run: `no`

Describe agent CLI capabilities

Example:

```bash
agent capabilities
agent capabilities --json
agent capabilities --view full
```

### `agent doctor`

- Anchor: `cmd-agent-doctor`
- Mutates state: `no`
- Supports dry run: `no`

Run agent CLI diagnostics

Example:

```bash
agent doctor
agent doctor --view full
```

### `agent explain`

- Anchor: `cmd-agent-explain`
- Mutates state: `no`
- Supports dry run: `no`

Explain how stdin could map to a target schema

Example:

```bash
agent explain
gmail message get m1 --jsonl | agent explain --to 'gcal event create'
gmail message get m1 --jsonl | agent explain --to 'gcal event create' --via intent.meeting_request.v1 --json
gmail message get m1 --jsonl | agent explain --to intent.task.v1
```

Flags:

- `--model` (string): Model profile name
- `--to` (string): Target command
- `--via` (string): Optional intermediate intent schema

### `agent login`

- Anchor: `cmd-agent-login`
- Mutates state: `yes`
- Supports dry run: `no`

No-op for local agent auth

Example:

```bash
agent auth login
agent login
```

### `agent logout`

- Anchor: `cmd-agent-logout`
- Mutates state: `yes`
- Supports dry run: `no`

No-op for local agent auth logout

Example:

```bash
agent auth logout
agent logout
```

### `agent model`

- Anchor: `cmd-agent-model`
- Mutates state: `no`
- Supports dry run: `no`

Manage model execution profiles

Example:

```bash
agent model add local
  agent model add local --provider ollama --model qwen3.5:2b
  agent model add work-openai --provider openai --model <model>
  agent model use local
  agent model list
```

#### `agent model add`

- Anchor: `cmd-agent-model-add`
- Mutates state: `yes`
- Supports dry run: `no`

Add or update a model execution profile

Example:

```bash
agent model add --help
agent model add gateway --provider custom --protocol openai-chat --base-url https://llm-gateway.example.com/v1 --model <model> --api-key-stdin
agent model add local
agent model add local --provider ollama --model qwen3.5:2b
agent model add work-openai --provider openai --model <model>
```

Flags:

- `--api-key-stdin` (bool): Read API key from stdin
- `--base-url` (string): Model endpoint base URL
- `--model` (string): Provider model name
- `--protocol` (string): Model protocol override
- `--provider` (string): Model provider: ollama|openai|anthropic|claude|gemini|custom
- `--structured-output` (bool): Backend supports structured JSON output Default: `true`.

#### `agent model list`

- Anchor: `cmd-agent-model-list`
- Mutates state: `no`
- Supports dry run: `no`

List model execution profiles

Example:

```bash
agent model list
agent model list --json
agent model list --view full
```

#### `agent model remove`

- Anchor: `cmd-agent-model-remove`
- Mutates state: `yes`
- Supports dry run: `no`

Remove a model execution profile and its stored API key

Example:

```bash
agent model remove --help
agent model remove local
```

#### `agent model show`

- Anchor: `cmd-agent-model-show`
- Mutates state: `no`
- Supports dry run: `no`

Show a model execution profile

Example:

```bash
agent model show
agent model show local --json
```

#### `agent model test`

- Anchor: `cmd-agent-model-test`
- Mutates state: `no`
- Supports dry run: `no`

Test a model execution profile

Example:

```bash
agent model test
agent model test local --json
```

#### `agent model use`

- Anchor: `cmd-agent-model-use`
- Mutates state: `yes`
- Supports dry run: `no`

Set the default model execution profile

Example:

```bash
agent model use --help
agent model use local
```

### `agent resolve`

- Anchor: `cmd-agent-resolve`
- Mutates state: `no`
- Supports dry run: `no`

Resolve an agent schema or command target

Resolve an intent schema id or a command target such as 'gcal event create'. This does not resolve item refs such as m1 or c1.

Example:

```bash
agent resolve
agent resolve 'gcal event create'
agent resolve 'gcal event create' --view full
agent resolve gmail message get --view full
agent resolve intent.contact.v1
```

### `agent schema`

- Anchor: `cmd-agent-schema`
- Mutates state: `no`
- Supports dry run: `no`

Show schema for a command or intent

Show schema for a command or intent.

Use --to for command targets and intent schema ids. The --via flag is accepted
as a compatibility alias for intent schema ids used with adapt/explain.

Example:

```bash
agent schema
agent schema --to 'gcal event create' --in --json
agent schema --to 'mscal event create' --in --json
agent schema --to intent.contact.v1 --out --json
agent schema --via intent.crm_activity.v1 --out --json
agent schema gcal event create --in --json
```

Flags:

- `--in` (bool): Show input schema
- `--out` (bool): Show output schema
- `--to` (string): Target command
- `--via` (string): Intent schema id alias for --to

### `agent validate`

- Anchor: `cmd-agent-validate`
- Mutates state: `no`
- Supports dry run: `no`

Validate stdin against a target or intent schema

Example:

```bash
agent validate
cat event.json | agent validate --to 'gcal event create'
cat task.json | agent validate --schema intent.task.v1
gmail message get m1 --jsonl | agent validate --schema intent.note.v1
```

Flags:

- `--schema` (string): Intent schema id
- `--to` (string): Target command

### `agent version`

- Anchor: `cmd-agent-version`
- Mutates state: `no`
- Supports dry run: `no`

Show agent version information

Example:

```bash
agent version
agent version --json
agent version --view full
```

## Live Examples

### Auth

#### Show local auth status

Shows that provider auth is delegated to source and target CLIs.

_Example metadata: provider state: local._

```bash
agent auth status
```

```text
Agent auth: local
Provider credentials: none needed
Model profile: local

Next: agent model list
```

### Lifecycle

#### Show capabilities

Lists local transform and validation capabilities.

_Example metadata: provider state: local._

```bash
agent capabilities
```

```text
agent capabilities
  auth       show local auth status
  capabilities
  doctor     run local diagnostics
  model      manage model execution profiles
  schema     inspect command and intent schemas
  transform
  validate   validate stdin against a schema
  version

Output: json, jsonl
Identifiers: stdin, schema_id, command_target

Next: agent schema --to intent.contact.v1 --out
```

### Schemas

#### Inspect an intent schema

Shows a discoverable intent schema.

_Example metadata: provider state: local._

```bash
agent schema --to intent.contact.v1 --out
```

```text
Schema: intent.contact.v1
Command: intent.contact.v1
Direction: output
Required: name, confidence

Next: agent validate --schema intent.contact.v1
```