QTG CLI & MCP — Reference

QTG ships 3 entry points for the control plane:

Binary	Surface	When to use
`qtg`	full role-aware (agent + minimal admin)	operator running commands from a shell
`qtg-agent`	agent-only subset (admin subcommands hidden)	LLM agent / CI / autopilot
`qtg-mcp`	stdio MCP server	Claude Desktop / Cursor / Claude Agent SDK

All 3 binaries share the existing environment-variable HMAC signing path. Role enforcement happens server-side (HMAC middleware ROLE_ALLOWED_ROUTES). The protected connection-file mode below is a bounded preparation surface, not onboarding, issuance, or activation.

Env vars (single set, all 3 binaries)

Var	Required	Meaning
`QTG_KEY_ID`	yes	HMAC `key_id` registered in `api_client_keys`
`QTG_HMAC_SECRET`	one of	raw secret string (lower priority)
`QTG_HMAC_SECRET_FILE`	one of	path to file containing secret (preferred — wins over raw)
`QTG_API_URL`	no	default `http://localhost:8100`
`QTG_AGENT_NAMESPACE`	yes for `qtg-mcp`, optional for `qtg-agent`	agent namespace (`agent/<authority_key>`)
`QTG_AUTHORITY_KEY`	no	explicit authority_key override (bypasses namespace derivation)
`QTG_OUTPUT`	no	`json` forces JSON output (CLI)

The shared HMAC client emits both X-MG-* and X-QTG-* headers (v3 nonce + timestamp), matching qtg.interfaces.api.middleware.auth.hmac.sign_request_headers.

Agent CLI (`qtg-agent`, 8 commands, read + propose only)

`qtg-agent balances`

qtg-agent balances --json

→ GET /v3/balances. Returns the balance view this agent can see.

`qtg-agent movements list / get / timeline`

qtg-agent movements list --limit 20
qtg-agent movements get <movement_id>
qtg-agent movements timeline <movement_id>

→ GET /v3/movements?limit=20, GET /v3/movements/{id}, GET /v3/movements/{id}/timeline.

`qtg-agent authority describe`

qtg-agent authority describe

→ GET /v3/agent-authorities/{authority_key}. The authority_key is derived from QTG_AGENT_NAMESPACE (strip agent/ prefix), or QTG_AUTHORITY_KEY if set, or fetched from /v3/whoami as fallback.

`qtg-agent template-proposals get`

qtg-agent template-proposals get <proposal_id>

→ GET /v3/template-proposals/{id}. Poll this after template-propose until status == "auto_promoted" (or admin promotes manually) to learn the resulting template_key.

`qtg-agent template-propose`

qtg-agent template-propose \
  --asset USDC \
  --protocol-family cex_to_cex \
  --proposal-kind static \
  --source-chain binance \
  --destination-chain arbitrum \
  --destination-chain-id 42161 \
  --destination-address 0xabc... \
  --signer-profile kms \
  --requested-notional 100 \
  --ttl-seconds 600

→ POST /v3/agent-authorities/{authority_key}/template-proposals. Side-effect free until promoted. Returns {proposal_id, status, ...}.

`qtg-agent bridge-attempt`

Same field set as template-propose plus optional --callback-url. D10 rule applies — propose only, no auto-execute.

No movement-run. The agent CLI is read + propose only — it cannot execute a movement. A movement an agent originates (via the API) always parks at PENDING_APPROVAL with agent_auto_approve_skipped, regardless of the operator’s auto_approve_enabled setting; a human promotes + approves.

Admin CLI (`qtg`)

qtg exposes all 8 agent commands plus the Free admin surface below. Venue checks (qtg venue probe/smoke) are implemented and wired today. Key/role provisioning (qtg admin keys / admin role) is still deferred to v0.2.0+ — use legacy seed_auth_client.py / bootstrap_admin_cli_key.py for that.

`qtg init`

qtg init --network testnet

Interactive local setup: can bring up PostgreSQL via compose, run the Alembic chain for public plus the selected network bucket, and render a .env from .env.example. It does not provision an inbound administrator credential, local signer, or agent authority. Walkthrough: Local Setup.

qtg init renders .env from .env.example, not from your live .env. Running it again after you have added keys by hand overwrites them.

Protected connection file (bounded preparation)

A protected POSIX connection file is supported only at the root of these commands:

qtg --connection-file /private/agent/connection.json auth check --json
qtg --connection-file /private/admin/connection.json auth revoke-credential \
  --credential-type hmac --credential-id TARGET --reason "incident" --yes --json
qtg-agent --connection-file /private/agent/connection.json auth check --json
qtg-mcp --connection-file /private/agent/connection.json

The metadata is an exact, data-only schema: required keys are schema_version, api_url, network, key_id, and secret_file; namespace and authority_key are optional for CLI and namespace is required for MCP. secret_file is a raw-secret filename, not secret JSON or a path; it must name a direct sibling in the same protected directory. For example, these synthetic values are structurally complete:

{
  "schema_version": "qtg-connection/v1",
  "api_url": "https://qtg.example.invalid",
  "network": "testnet",
  "key_id": "example-agent-key",
  "namespace": "agent/example-agent",
  "authority_key": "example-agent",
  "secret_file": "secret"
}

The URL must be HTTPS (except exact loopback HTTP) and carries no query, fragment, or userinfo. network is exactly mainnet or testnet. When both namespace and authority_key are supplied, agent/<key> normalization must make them the same identity; contradictions fail before HTTP. The directory and both files must be owned by the invoking user, with directory mode 0700 and file mode 0600; symlinks, symlinked traversal, broad permissions, raw secrets in JSON, unknown fields, and ambient QTG_* fallback are rejected. The selected network becomes X-QTG-Network; a different process network fails closed. No other --connection-file command is supported: local, venue, top-up, Pro, help, and ordinary agent paths fail before file loading or command execution. auth check only reads authenticated identity and, for a matching agent namespace, its existing authority record. It does not evaluate policy, approval, provider, or live readiness. An omitted or mismatching agent namespace is non-success. File-selected revoke requires literal --yes; it still uses the server’s exact-current-credential revoke rules. The legacy env-only revoke command remains compatible without --yes. File-selected CLI failures with --json return only {"operation":"...","code":"..."} on stdout and the code on stderr. MCP rejects invalid file/role/namespace/network startup contexts with only a stable code and returns bounded operation/code errors from existing tools; it neither adds tools nor grants permissions. This does not bootstrap an administrator, issue a credential, authenticate pending keys, activate policy, or make a process movement-ready. Existing stored-secret-at-rest risks and legacy secret-output surfaces remain outside this preparation slice.

`qtg whoami`

qtg whoami

→ GET /v3/whoami. Returns {client_id, key_id, role, namespace?}. Useful sanity check for key/secret setup.

`qtg audit query`

qtg audit query --action movement.create --outcome denied --limit 50

→ GET /v3/audit/events. Supported filters mirror src/qtg/interfaces/api/routes/audit.py (:59-98) exactly: --time-range-start, --time-range-end, --actor-client-id, --actor-key-id, --entity-type, --entity-key, --action, --request-id, --outcome, --namespace, --cursor, --limit.

`qtg template promote`

qtg template promote <proposal_id>

→ POST /v3/template-proposals/{proposal_id}/promote. Admin-only. Promotion is governed: the route returns 409 CONFIG_PROPOSAL_REQUIRED; promote through an agent_authority_proposal.promote configuration proposal applied by a second admin.

`qtg template patch`

qtg template patch <template_key> --namespace <namespace>

→ PATCH /v3/plan-templates/{template_key}. --namespace is the only field this command sends. The auto-approve toggle and caps are governed — the raw HTTP route returns 409 CONFIG_PROPOSAL_REQUIRED for them — so change them through a route_template.auto_approve configuration proposal (see Auto-Approve).

`qtg allowlist list`

qtg allowlist list --chain-family evm --chain-id 8453
qtg allowlist list --include-inactive

→ GET /dashboard/allowed-addresses. Read-only view of the address allowlist that guards fund movement. Filters: --chain-family (evm | cex), --chain-id, --include-inactive (adds revoked rows). A row with "chain_id": null is an any-chain wildcard — it authorises the address on every chain of its family. Review those first when auditing. The group is read-only by design. Registering and revoking stay on the audited write surfaces — python -m qtg.interfaces.tools.seed_allowed_address / ... .revoke_allowed_address, or the dashboard writer-HMAC routes — because a convenience CLI mutation on a fund-safety gate is an open security decision. See Runbook — Address Allowlist Management.

`qtg chain probe`

qtg chain probe base_sepolia --rpc-url https://... --usdc 0x...

Reports whether a chain’s CCTP and Gateway lanes are actually open before you route funds through them. Read-only. Each lane also probes a domain that must not exist, so an endpoint that answers everything identically cannot read as GO. Exits non-zero unless every requested lane passes.

`qtg agent-wallet topup`

The Agent Wallet top-up stage ladder — preflight, env-probe, init-packet, seed-stage1, drill-stage2, live-stage3, validate-packet. init-packet requires an explicit --output-dir; use an operator-private directory outside publishing or shared branches, as an explicit path does not prove privacy. Only live-stage3 can sign or broadcast, and it requires an explicit acknowledgement flag. See Agent Wallet.

`qtg testnet-truncate`

Truncates every network-scoped table in the testnet schema. Prompts unless --yes is passed. There is no mainnet equivalent.

Human session CLI (`qtg human`)

JEP-877 protected human action / JEP-919 CLI onboarding surface — a closed, local-only human session plane, separate from the HMAC auth commands and not a credential issuance path:

qtg human login --origin <origin> --network <network>   # open a human session
qtg human inspect                                        # show active session state
qtg human logout                                         # clear the session
qtg bootstrap-human-owner                                # bootstrap the human owner (one-off)
qtg core-local                                           # local core tooling entrypoint

Registered on both qtg and qtg-agent; browser-wallet opt-in (KMS/SIWE) stays disabled by default.

Venue CLI (`qtg venue`)

Adapter health check + live smoke test. See guide/venue-smoke-test.md for the end-to-end walkthrough.

`qtg venue probe`

qtg venue probe <venue> --asset USDC --network ethereum

Read-only adapter health check — verifies credentials and connectivity for the named exchange (e.g. binance, upbit, bybit). Exits non-zero if the probe fails. Runs the probe harness locally; no movement is created.

`qtg venue smoke`

qtg venue smoke <source> \
  --dest <destination> \
  --asset USDC \
  --network ethereum \
  --amount 5 \
  --max-source-debit 5.5 \
  --timeout 300

Live smoke test — sends a small stablecoin transfer (capped at $5) through the full movement lifecycle and observes settlement. --max-source-debit is required and must be ≥ --amount: it is threaded into approval as the operator-approved CEX fee-on-top source-debit authority, so a withdrawal whose gross debit exceeds it is rejected. Prompts for confirmation unless --no-confirm is passed. --timeout bounds the observe phase (default 300s). Exits 0 only when the movement reaches COMPLETED; exit 1 when one or more probes/transfer steps fail, exit 2 for unknown venue or missing credentials.

MCP server — Claude Desktop / Cursor

qtg-mcp is a stdio MCP server exposing 8 read+propose tools to MCP-aware clients (no movement-execution tool).

`claude_desktop_config.json`

{
  "mcpServers": {
    "qtg": {
      "command": "qtg-mcp",
      "env": {
        "QTG_KEY_ID": "agent-key-001",
        "QTG_HMAC_SECRET_FILE": "/path/to/agent_hmac_secret",
        "QTG_API_URL": "http://localhost:8100",
        "QTG_AGENT_NAMESPACE": "agent/auth_alpha"
      }
    }
  }
}

Tool list

Tool	HTTP
`qtg_balances`	`GET /v3/balances`
`qtg_movements_list(limit)`	`GET /v3/movements?limit=...`
`qtg_movement_get(movement_id)`	`GET /v3/movements/{id}`
`qtg_movement_timeline(movement_id)`	`GET /v3/movements/{id}/timeline`
`qtg_template_proposals_get(proposal_id)`	`GET /v3/template-proposals/{id}`
`qtg_authority_describe()`	`GET /v3/agent-authorities/{authority_key}`
`qtg_template_propose(asset, protocol_family, ...)`	`POST /v3/agent-authorities/{authority_key}/template-proposals`
`qtg_bridge_attempt(asset, protocol_family, ...)`	`POST /v3/agent-authorities/{authority_key}/bridge-attempt`

Boot-time role probe (fail-fast)

qtg-mcp does a synchronous GET /v3/whoami before opening the stdio handshake. If:

the env is incomplete → exit 2 with stderr qtg-mcp: config error: ...
whoami HTTP fails → exit 1 with stderr qtg-mcp: whoami probe failed: ...
role != agent → exit 1 with stderr qtg-mcp: refusing to start — key role is 'admin', expected 'agent'
env namespace != server-reported namespace → exit 1 with stderr qtg-mcp: namespace mismatch — ...

This prevents silent registration in Claude Desktop with a misconfigured key.

e2e smoke runbook

# 1. Seed an agent key + AgentAuthority in dev DB.
# 2. Export env:
export QTG_KEY_ID=agent-key-001
export QTG_HMAC_SECRET_FILE=/path/to/secret
export QTG_API_URL=http://localhost:8100
export QTG_AGENT_NAMESPACE=agent/auth_alpha

# 3. Run dev server (separate shell).
uv run uvicorn qtg.main:app --reload --port 8100

# 4. Smoke test:
qtg whoami                 # role=agent + namespace (whoami is on the `qtg` binary only)
qtg-agent balances --json  # should return the balance shape

# 5. MCP subprocess:
qtg-mcp <<< '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# → JSON response listing 8 tools.

# 6. (Opt-in pytest e2e — requires dev server running)
QTG_MCP_E2E=1 \
  QTG_E2E_AGENT_KEY_ID=$QTG_KEY_ID \
  QTG_E2E_AGENT_SECRET=$(cat /path/to/secret) \
  QTG_E2E_AGENT_NAMESPACE=$QTG_AGENT_NAMESPACE \
  uv run pytest tests/qtg/mcp_server/test_mcp_e2e.py -v

Out of scope (v0.1.0 GA)

Template discovery (qtg-agent templates list/search) — v0.2.0
Streamable HTTP MCP transport — v0.2.0+ (stdio only for now)
qtg admin keys / admin role (key/role provisioning) — server routes pending; use legacy seed_auth_client.py for now.
Migration of 55+ legacy admin tools — v0.2.0+ gradual
Colored / pretty CLI output (rich) — v0.2.0+
Windows shell compatibility — macOS + Linux verified only

Overview

Domain Model

Executors

Signers

Infrastructure

CLI & MCP

Security

CLI Reference

QTG CLI & MCP — Reference

Env vars (single set, all 3 binaries)

Agent CLI (`qtg-agent`, 8 commands, read + propose only)

`qtg-agent balances`

`qtg-agent movements list / get / timeline`

`qtg-agent authority describe`

`qtg-agent template-proposals get`

`qtg-agent template-propose`

`qtg-agent bridge-attempt`

Admin CLI (`qtg`)

`qtg init`

Protected connection file (bounded preparation)

`qtg whoami`

`qtg audit query`

`qtg template promote`

`qtg template patch`

`qtg allowlist list`

`qtg chain probe`

`qtg agent-wallet topup`

`qtg testnet-truncate`

Human session CLI (`qtg human`)

Venue CLI (`qtg venue`)

`qtg venue probe`

`qtg venue smoke`

MCP server — Claude Desktop / Cursor

`claude_desktop_config.json`

Tool list

Boot-time role probe (fail-fast)

e2e smoke runbook

Out of scope (v0.1.0 GA)

​QTG CLI & MCP — Reference

​Env vars (single set, all 3 binaries)

​Agent CLI (qtg-agent, 8 commands, read + propose only)

​qtg-agent balances

​qtg-agent movements list / get / timeline

​qtg-agent authority describe

​qtg-agent template-proposals get

​qtg-agent template-propose

​qtg-agent bridge-attempt

​Admin CLI (qtg)

​qtg init

​Protected connection file (bounded preparation)

​qtg whoami

​qtg audit query

​qtg template promote

​qtg template patch

​qtg allowlist list

​qtg chain probe

​qtg agent-wallet topup

​qtg testnet-truncate

​Human session CLI (qtg human)

​Venue CLI (qtg venue)

​qtg venue probe

​qtg venue smoke

​MCP server — Claude Desktop / Cursor

​claude_desktop_config.json

​Tool list

​Boot-time role probe (fail-fast)

​e2e smoke runbook

​Out of scope (v0.1.0 GA)

QTG CLI & MCP — Reference

Env vars (single set, all 3 binaries)

Agent CLI (`qtg-agent`, 8 commands, read + propose only)

`qtg-agent balances`

`qtg-agent movements list / get / timeline`

`qtg-agent authority describe`

`qtg-agent template-proposals get`

`qtg-agent template-propose`

`qtg-agent bridge-attempt`

Admin CLI (`qtg`)

`qtg init`

Protected connection file (bounded preparation)

`qtg whoami`

`qtg audit query`

`qtg template promote`

`qtg template patch`

`qtg allowlist list`

`qtg chain probe`

`qtg agent-wallet topup`

`qtg testnet-truncate`

Human session CLI (`qtg human`)

Venue CLI (`qtg venue`)

`qtg venue probe`

`qtg venue smoke`

MCP server — Claude Desktop / Cursor

`claude_desktop_config.json`

Tool list

Boot-time role probe (fail-fast)

e2e smoke runbook

Out of scope (v0.1.0 GA)