Skip to main content
HUMΛN

human companion

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

Flag Description
--repl Interactive REPL instead of a one-shot message
--session <id> Resume context — sent as X-Session-Id on the request
--json Print the final CompanionCLIResult (content, structured, session_id) as JSON
--no-stream Use JSON response instead of SSE; print the full reply at the end
--quiet Suppress incremental token streaming (errors still shown)
--copy After single-shot, copy the assistant’s final text to the clipboard
--pager After single-shot, open the assistant’s final text in less (Unix/macOS) or more (Windows)
--no-pager Never open less (disables --pager and auto-pager)
--no-progress Disable the “Calling Companion…” spinner and SSE progress bar
--replay-c2c REPL only: on start, walk unread C2C via GET /v1/companion/c2c/inbox?status=unread (same prompts as SSE)
--replay-c2c-limit <n> REPL only: with --replay-c2c, max unread items to walk (1–50, default 10 or HUMAN_COMPANION_REPLAY_C2C_LIMIT)
--restore-canvas REPL only: on start, print recent canvas specs (GET /v1/companion/canvas + per-id GET). Passport-scoped (your recently updated canvases), not filtered by task_id / --session.
--pick-history REPL only: before the first prompt, fuzzy-pick a prior line from local history and send it as the first turn

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

Variable / profile Role
HUMAN_API_URL / profile apiUrl API base (default http://localhost:3001)
HUMAN_DELEGATION_TOKEN / profile token Bearer auth
HUMAN_CONSOLE_URL Base URL for C2C canvas.invite deep links in the terminal (default https://console.haio.run)
HUMAN_COMPANION_AUTO_PAGER 1 / true — opt-in auto-less for long single-shot replies (TTY)
HUMAN_COMPANION_REPLAY_C2C 1 / true — REPL start: same as --replay-c2c
HUMAN_COMPANION_REPLAY_C2C_LIMIT Integer 1–50 — default max unread C2C items (default 10; overridden by --replay-c2c-limit)
HUMAN_COMPANION_RESTORE_CANVAS 1 / true — REPL start: same as --restore-canvas
HUMAN_COMPANION_RESTORE_CANVAS_SPECS Integer 1–8 — how many full canvas specs to print (default 3)
PAGER=cat Disables companion pager (manual and auto)

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"
Flag Description
--name Internal slug, unique per org (required)
--surface-label Operator tag, e.g. marketing-site (required)
--display-name Brand name shown in widget chrome (default: HUMΛN)
--target Agent URI (default: agent://org/human/companion@0.1)
--allowed-origins Comma-separated origin allowlist (empty = any origin)
--prompt-id Prompt registry URI (default: org default)
--allowed-extension-bundles Comma-separated bundle IDs the agent may auto-execute
--json Print response as JSON

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.

← All CLI commands