human companion

Use the same Companion agent as the web UI from your terminal: natural language, connector slash commands (/v1/companion/commands), directory-backed @mentions, and readable fallbacks for canvas and C2C events. Requests are tagged with source_surface: cli for provenance.

Prerequisites

API: POST /v1/agents/call with SSE (Companion agent + CommandRouter path).

Auth: Delegation JWT — human login or HUMAN_DELEGATION_TOKEN (or profile apiKey).

Optional APIs: GET /v1/companion/directory for @ resolution in the REPL; GET /v1/companion/commands and POST /v1/companion/commands/resolve for / slash flow.

Single-shot

human companion "Summarize open incidents for my org"
human companion --session "<task_id>" "Continue where we left off"

Streams token deltas to stdout by default. On completion, the session id (from the gateway) is printed dimmed when not using --quiet.

Flags

REPL

human companion --repl
human companion --repl --session "<task_id>"
human companion --repl --session "<task_id>" --restore-canvas --replay-c2c --replay-c2c-limit 5
human companion --repl --pick-history

Prompt: companion>

Built-ins: /help, /exit or /quit, /hist or /r (fuzzy pick from ~/.human/companion/history.jsonl, mirrored to history.json for tooling)

Slash commands: Any other line starting with / runs the connector command flow: cached command list, fuzzy filter/select, commands/resolve, interactive prompts for missing required params, then the composed message is sent to the Companion.

@mentions: After you submit a line, @handle segments are resolved via GET /v1/companion/directory?q=…; multiple matches use the same numbered/fuzzy pattern as other CLI flows. Resolved DIDs are sent as cli_mention_resolutions so the agent can skip redundant directory work.

Subcommand: human companion commands

Lists installed connector commands for your org (paginated under the hood).

human companion commands
human companion commands --json

Table columns: qualified_name, connector, description, surfaces.

Theme & progress

Theme: Optional ~/.human/companion/theme.json — e.g. { "stream_color": "cyan", "auto_pager": true } (white, gray, cyan, …) tints streamed token output; auto_pager opts into the same behavior as HUMAN_COMPANION_AUTO_PAGER=1.

Progress: Default TTY single-shot shows an ora spinner until the stream starts, then a cli-progress bar that ticks per SSE frame (disable with --no-progress).

Auto-pager (single-shot): When HUMAN_COMPANION_AUTO_PAGER=1 or theme.auto_pager is true, a long final reply (many lines vs terminal height, or very large character count) opens in less after streaming unless --no-pager is set. Auto-pager is off when --quiet is set (streaming is already suppressed). Set PAGER=cat to disable all paging; if you still pass --pager, the CLI prints a one-line hint on stderr that less was skipped.

Output behavior

Tokens: Stream color follows theme (default white).

Structured / canvas: canvas_open / deltas coerced to CanvasSpec and rendered with tables, rich_report markdown (headers, lists, fenced code via syntax highlighting), code_block with cli-highlight, summaries for chart/map/graph, etc.

C2C: c2c_inbox lines drive terminal prompts (meeting, approval, canvas invite, alert) and PATCH /v1/companion/c2c/:message_id/respond when you confirm.

Environment

Subcommand: human companion deployment

Manage named Companion deployments — each deployment is an independently configured embeddable widget instance with its own scoped token, allowed origins, and optional persona.

human companion deployment create   # create a new deployment + mint token
human companion deployment list     # list all deployments for the org
human companion deployment show     # show one deployment's details
human companion deployment update   # update name, origins, display name, etc.
human companion deployment delete   # deactivate and revoke token
human companion deployment rotate   # mint a new token (old immediately invalid)
human companion deployment snippet  # print the copy-paste embed snippet

deployment create

human companion deployment create \
  --name "Support Portal" \
  --surface-label "customer-support" \
  --display-name "Aria" \
  --allowed-origins "https://support.acme.com" \
  --prompt-id "companion.system@acme-support-v1" \
  --allowed-extension-bundles "helpdesk,github"

deployment list

human companion deployment list
human companion deployment list --json

deployment show

human companion deployment show --id dep_abc123
human companion deployment show --name "Support Portal"

deployment update

human companion deployment update dep_abc123 \
  --display-name "Aria v2" \
  --allowed-origins "https://support.acme.com,https://help.acme.com" \
  --allowed-extension-bundles "helpdesk"

deployment delete

human companion deployment delete dep_abc123
human companion deployment delete dep_abc123 --force  # skip confirmation

deployment rotate

Mints a new delegation token and immediately invalidates the old one. Prints the updated embed snippet.

human companion deployment rotate dep_abc123

deployment snippet

Prints the two-line embed snippet for the deployment.

human companion deployment snippet --id dep_abc123
human companion deployment snippet --name "Support Portal"

---

Shell completion

human completion bash|zsh|fish includes companion and its flags plus the commands and deployment subcommands.

Authentication

Same as other platform CLIs: run human login or set HUMAN_DELEGATION_TOKEN with an org-scoped delegation.