Canvass CLI

The Canvass CLI is the preferred way to give Claude Code, Codex, Cursor, Grok Bot, Hermes, or a background worker governed access to Canvass. 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 CLI owns connection lifecycle and local secret handling. MCP is the tool transport the CLI installs for compatible agent clients; it does not replace the CLI's enrollment, keychain, diagnostics, or recovery work. Use direct authenticated HTTP or remote MCP only when the runtime cannot execute the CLI, or when the generated handoff says an exact custom permission set cannot be represented by a CLI preset.

The one-minute path

1. In Canvass, choose Connect an agent.
2. Name the agent, choose the smallest job it needs, and create the pairing message.
3. Give the complete generated message to the agent unchanged. It contains the selected role, campaign scope, connection lifecycle, and operating rules. 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://canvass.fabric.pro/install.sh | sh
gtm version

Windows PowerShell:

irm https://canvass.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 Plan across workspace. It reads approved GTM workspace context and proposes drafts for review, but it cannot run live campaign actions. Ask for another certified preset only when the job needs narrower or executable access:

printf '%s' "$GTM_PAIRING_CODE" | gtm connect \
  --code-stdin \
  --name "Workspace planning assistant" \
  --request workspace-planner \
  --non-interactive \
  --json

For lead-only research:

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.

For an autonomous campaign builder, request the complete reviewed campaign surface and bind it to the exact campaign IDs it may operate. The administrator still reviews the action set, and prospect-visible delivery remains governed by the campaign's human-approval policy:

printf '%s' "$GTM_PAIRING_CODE" | gtm connect \
  --code-stdin \
  --name "Campaign operator" \
  --request campaign-operator \
  --campaigns <campaign-id> \
  --non-interactive \
  --json

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.

From ICP to governed delivery

Use this sequence for autonomous campaign work. Friendly commands are conveniences over the same catalog resources and Platform actions exposed through MCP and authenticated HTTP:

1. Run gtm catalog --json, then inspect gtm workspace show, gtm icp list, and gtm campaigns list.
2. Create or revise the campaign's ICP with gtm icp create or gtm icp update, then use gtm icp activate for the intended version. A new ICP does not replace or rebind existing campaigns; each campaign retains its exact versioned audience context.
3. Import or update qualified companies and people using only commands reported available by gtm capabilities --json. Provider search and list membership reads remain unavailable until the live catalog exposes privacy-safe projections.
4. Use gtm messaging policy-save and gtm messaging policy-activate, create or update the campaign, then persist its working copies with gtm artifacts draft or gtm artifacts update.
5. Run gtm campaigns check, resolve every named blocker, and perform a dry run.
6. Run gtm campaigns launch --no-wait only when the operator intends to request governed delivery. Instantly activation and prospect-visible sending remain subject to the exact campaign grant, suppression checks, delivery authorization, and human approval.
7. Follow the returned operation with gtm operations watch <operation-id> to a terminal status and report the campaign name, outcome, and next human action. Use IDs only in structured receipts or to disambiguate names.

See Agent capability parity for generated coverage and explicit exceptions. Never improvise a substitute command for an unavailable capability.

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

Run gtm doctor --json before consuming a one-time pairing code. The OS keychain is the default. On a headless server without one, explicitly opt into the permission-checked 0600 fallback with --allow-file-secret-store only when the runtime has a private, persistent home directory. File fallback is never implicit and must not be used on shared or ephemeral storage. Disconnect fails closed if secret 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://canvass.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.