GTM CLI

The GTM CLI is the simplest way to give Claude Code, Codex, Cursor, Grok Bot, Hermes, or a background worker governed access to GTM Brain. It handles enrollment, keeps credentials out of chat, and exposes the same live catalog and governed actions as the product UI. Tenant, campaign, policy, approval, pause, audit, and idempotency checks remain server-enforced.

The one-minute path

1. In GTM Brain, choose Connect an agent.
2. Name the agent, choose the smallest job it needs, and create the pairing message.
3. Give the message to the agent. Pairing codes are single-use and expire after 24 hours.
4. In the agent's private terminal, run:

printf '%s' "$GTM_PAIRING_CODE" | gtm connect --code-stdin

5. Review the request in Approvals. An administrator may approve or narrow it.
6. The CLI claims the credential into the OS keychain and verifies the granted catalog. It never prints the credential.
7. Connect the local MCP bridge, restart the agent, and ask it to call get_catalog:

gtm agents detect
gtm agents install auto

A good first prompt is “Show our ICPs.”

Install

macOS and Linux:

curl -fsSL https://gtm.fabric.pro/install.sh | sh
gtm version

Windows PowerShell:

irm https://gtm.fabric.pro/install.ps1 | iex
gtm version

The Unix installer defaults to ~/.local/bin/gtm; set GTM_CLI_INSTALL_DIR to choose another location. Official releases cover macOS, Linux, and Windows on amd64 and arm64. Installers verify SHA-256 before replacing the executable. Releases also include an SBOM and GitHub build-provenance attestation.

Connect safely

Interactive use:

gtm connect GTM-7K4Q-9H2M

For agents and shell history, prefer stdin:

printf '%s' "$GTM_PAIRING_CODE" | gtm connect \
  --code-stdin \
  --name "Campaign copy assistant"

The default request is Write and review copy. It reads approved context and proposes drafts, but it cannot send. Ask for another certified preset only when the job needs it:

printf '%s' "$GTM_PAIRING_CODE" | gtm connect \
  --code-stdin \
  --name "Lead research worker" \
  --request lead-researcher \
  --non-interactive \
  --json

Use --campaigns <id[,id...]> to limit access to specific campaigns. Proposal-only copy and research requests do not require a live campaign. While approval is pending, leave the command running or resume the exact enrollment with gtm status --json. Status never mints a replacement key.

Connect an agent client

gtm agents detect --json
gtm agents install auto

Or choose one explicitly:

gtm agents install claude
gtm agents install codex
gtm agents install cursor

Claude Code and Codex use their official MCP commands. Cursor receives a managed gtm stdio entry. For another standards-compatible client, run gtm agents instructions --json and configure the shown command. The local server is simply:

gtm mcp

The bridge forwards JSON-RPC to the registration-bound remote MCP endpoint. It suppresses notification responses, converts malformed or empty upstream responses into explicit errors, and never widens the server catalog.

Command reference

Use --profile <name> for multiple workspaces or agent identities. Use --json for automation. Every typed mutation accepts --input <file|->, repeatable --set key=JSON, --dry-run, an optional --idempotency-key, and --wait or --no-wait. When no key is supplied, the CLI derives a stable key from the exact action and canonical JSON parameters, so repeating the same logical command is safe. The server catalog still decides whether the action is available and whether approval is required.

Inspect the current registration before automation:

gtm capabilities --json
gtm campaigns launch --dry-run --input campaign-pass.json --json
gtm campaigns launch --wait --input campaign-pass.json --json
gtm operations watch <operation-id> --timeout 10m --json

The stable process exit contract is 0 for success and 1 for usage, authorization, approval, availability, validation, transport, or operation failure. Structured failures include a stable code and human-actionable message; automation should branch on code, not localized prose.

Read the live catalog first

gtm catalog --json

The catalog is the truth for this registration now. It advertises only granted resources and actions. A paused, expired, disabled, or campaign-less registration returns non-retryable recovery guidance and the setup deep link instead of pretending that zero tools is success. Agents should call get_catalog at the beginning of every session and after an administrator changes access.

Invoke a governed action

gtm run gtm.save_reply_draft \
  --input request.json \
  --idempotency-key draft-acme-followup-v1 \
  --json

Every mutation requires a caller-stable idempotency key. If a response is interrupted or ambiguous, retry with the same key and equivalent input. Never create a new key merely because the first response was lost. Inspect durable work with:

gtm operations get <action-invocation-id> --json

The CLI cannot bypass proposal-only access, human approval, suppression, campaign scope, tenant pause, or delivery policy.

Background workers and CI

printf '%s' "$GTM_PAIRING_CODE" | gtm connect \
  --code-stdin \
  --profile nightly-research \
  --name "Nightly research worker" \
  --request lead-researcher \
  --non-interactive \
  --json

The OS keychain is the default. On a server without one, inject a tenant-bound secret through the platform secret manager or explicitly opt into the permission-checked 0600 fallback with --allow-file-secret-store. File fallback is never implicit. Disconnect fails closed if keychain deletion cannot be confirmed.

Supply credentials to one legacy child without exporting them into the parent shell:

gtm credentials exec --profile nightly-research -- ./worker

Troubleshooting

Start with:

gtm doctor --json
gtm status --json
gtm catalog --json

Public pairing failures are deliberately generic to prevent code enumeration.

Disconnect, pause, revoke, and replace

gtm disconnect --profile nightly-research --json

Disconnect removes local state only. An administrator pauses or revokes server access in Team & agents. If a reveal-once credential is lost, replace the connection; replay recovers the receipt, not the key.

Update and verify

gtm update --check
curl -fsSL https://gtm.fabric.pro/install.sh | sh

Versioned archives are immutable under /releases/gtm-cli/v<version>/; latest.txt moves only after all six archives and checksums exist. Installers reject checksum mismatches, unsafe version paths, and unapproved alternate origins.

Security model

• Pairing codes are single-use, expire after 24 hours, and resolve through a high-entropy secret.
• The agent asks; the administrator may approve or narrow, never silently widen.
• Credentials are reveal-once, tenant-bound, hashed server-side, and stored in the OS keychain by default.
• GTM rechecks registration, grant, scope, pause, policy, and action constraints at execution time.
• Prospect-visible work remains proposal-only until human approval and delivery checks pass.
• Credentials and enrollment secrets are excluded from normal output, durable action parameters, logs, and MCP errors.

Next: Connect outside agents, Team & agents, and Approvals.