Operator Guide: The tp Host CLI

Audience: Federated and standalone registry operators (self-hosted) Prerequisite: A running operator stack and its .env.operatorLast Updated: 2026-07-17

---

1. What It Is

Your operator bundle ships a single-binary day-2 operations CLI alongside the compose files -- no Python, no dependencies, linux/amd64 and linux/arm64 builds. It automates the routine of running a registry from the host: health checks, log tailing, restarts, license management, agent SPIRE enrollment, backups, restores, and bundle updates.

Two entry points, one command surface:

• tp -- the umbrella binary. Day-2 ops live under tp operator <command>; it also exposes tp mcp (an MCP server mode, section 8) and reserved tp developer / tp admin personas (currently stubs).
• tp-operator -- the standalone alias kept for compatibility. tp operator status and tp-operator status route to the same code.

Install whichever matches your architecture:

case "$(uname -m)" in
  x86_64|amd64)  install -m 0755 tp-operator       /usr/local/bin/tp-operator ;;
  aarch64|arm64) install -m 0755 tp-operator-arm64 /usr/local/bin/tp-operator ;;
esac
tp-operator version

The CLI is day-2 only. First-run bootstrap is still ./operator-setup.sh -- the CLI assumes an .env.operator already exists.

---

2. Auth Model

One primitive, one secret. The CLI reads FEDERATION_LICENSE_KEY from your .env.operator and presents it as X-Federation-License: tp_fed_... on every call to your parent frame. No developer JWT, no password prompts, no shared internal secrets.

The only exception is the bundle command group (section 7), which manages agent bundles on the registry API and therefore authenticates with a developer API key (--api-key).

---

3. Local Stack Operations

Command	What it does
status [--detail]	Aggregate stack health snapshot (compose ps + a green/yellow/red verdict). --detail adds start time and restart counts.
health [--strict]	Active HTTP probe of your parent frame's /health. --strict also probes the federation and EventStore endpoints.
logs <service> [--tail N] [-f] [--since ...]	Tail one service's logs. Services: registry, teg-layer, db, teg-db, redis, pgbouncer, nginx-federation, spire-agent, cert-writer.
restart [<service>] [--apply-env-changes] [--no-wait]	Restart one service, or the whole stack if omitted. --apply-env-changes force-recreates so edited env vars take effect.
start / stop	Bring the stack up (docker compose up -d) / down (docker compose down).
doctor	Full operator-side diagnostic -- Docker daemon, free disk, services running, license present, parent-frame reachability. Paste its output into support tickets.
validate-config [--proposed PATH]	Pre-flight schema and coupling checks on .env.operator -- validate a proposed file before you apply it.
version	Print CLI + schema versions.

---

4. Federation Operations

Command	What it does
peers	Federation network stats and per-peer status from your parent frame.
sync	Trigger a federation sync cycle now (calls /federation/sync) instead of waiting for the background worker.
license show	Print the local license summary from .env.operator.
license verify	Probe the parent frame -- is your federation license still active?
license rotate --reason <reason>	Self-serve license key rotation. Reasons: leak_suspected, scheduled_rotation, post_incident. The CLI updates .env.operator with the new key.

---

5. Agent mTLS (spire)

Manage your agents' SPIRE entries (the IRONHAND agent-identity surface) without touching the SPIRE server directly:

Command	What it does
spire list	List this operator's enrolled agents.
spire enroll <agent-did> [--parent-fingerprint ...]	Register a SPIRE entry for an agent (defaults to OPERATOR_SPIRE_AGENT_FINGERPRINT from .env.operator).
spire revoke <agent-did>	Delete an agent's SPIRE entry.

---

6. Disaster Recovery & Updates

Command	What it does
backup [--out PATH]	Atomic backup: pg_dump of both databases + configs + a manifest, in one archive.
restore <archive> [--rebuild-volumes] [--skip-env-restore]	Atomic restore from a backup archive, with safety nets (single-operator only; cross-operator restore requires an explicit --force-cross-operator).
update [--check-only|--apply] [--to-version X] [--allow-major] [--no-auto-rollback]	Check for (default) or apply a new operator bundle. Applies run a post-apply health check and auto-roll back on failure unless disabled.

Destructive commands ask for confirmation; pass --yes in scripts.

---

7. Agent Bundles (bundle)

CLI surface for the signed .tpb agent-bundle feature -- authenticated with a developer API key, not the federation license:

bundle list [--kind snapshot|template|migration] [--no-official]
bundle create --agent-did <did> [...] [--kind ...] [--visibility ...] [--out file.tpb]
bundle download <bundle-id> [--out file.tpb]
bundle restore <file.tpb> [--conflict skip|rename|overwrite] [--mode copy|mirror]
bundle verify <file.tpb>
bundle quota <developer-id>        # admin-only

---

8. MCP Server Mode

tp mcp serve runs a stdio MCP server that exposes the CLI verbs as MCP tools, so an MCP client (e.g. Claude Code) can drive your host operations -- status, logs, restart, backup, spire enrollment, license checks -- through your .mcp.json. tp mcp tools lists the tools it would expose; tp mcp version prints protocol info.

---

9. Global Flags

Every command honors:

--operator NAME       pick an operator on a multi-operator host
--all-operators       apply across every discovered operator (bulk read/write)
--config PATH         explicit .env.operator path
--json                machine-readable JSON (for CI)
--quiet               errors only (cron-friendly)
--yes / -y            skip interactive confirms
--dry-run             print the intended action, execute nothing
--no-color            disable rich formatting
--verbose / -v        more output (repeatable)
--timeout SECONDS     HTTP timeout (default 30)

Tab completion: tp-operator --show-completion bash > /etc/bash_completion.d/tp-operator (zsh supported too).

---

10. Exit Codes

Code	Meaning
0	Success
1	User error (bad args, validation fail)
2	System error (uncaught exception)
3	Network error
4	Auth error
5	Docker unreachable
6	docker-compose error
7	Parent frame unreachable
8	Partial success (multi-operator)
130	Interrupted (Ctrl-C)

---

11. Cron One-Liners

# Daily 03:00 backup
0 3 * * * tp-operator backup --out /opt/backups/$(date +\%Y\%m\%d).tar.gz --yes --quiet

# Every 5 min: alert when the stack is not green
*/5 * * * * tp-operator status --json --quiet | jq -e '.verdict == "green"' || /usr/local/bin/alert.sh

# Weekly: check for bundle updates
0 9 * * 1 tp-operator update --check-only --json | jq -e '.update_available' && /usr/local/bin/notify.sh