CLI Reference

The tappass CLI is the operator interface to TapPass. Workspace commands (agents, audit, policy, approvals, connectors, …) run against your configured server — set it once with tappass config set server <url> or override per invocation with --server/-s. Host commands (up, db, backup) run on the machine where the TapPass server is installed. Pass -h/--help on any subcommand for inline reference, --version/-V for the version block (--output json for machine-readable).

Value resolution

Every command resolves shared values in this order:

--flag  >  $TAPPASS_<KEY_UPPER_SNAKE>  >  active context  >  builtin default  >  error

So --org-id acme beats $TAPPASS_ORG_ID, which beats the org-id stored in the active context. Contexts live in ~/.tappass/config.toml (non-secret values only — the session JWT is stored separately at ~/.tappass/session).

tappass config — named contexts

Like gcloud config configurations: one named context per environment.

Command	Description
tappass config set <key> <value> [--context NAME]	Set a key (server, org-id, project-id, …); creates the context if missing
tappass config get <key> [--context NAME]	Print one value (exit 5 if unset)
tappass config unset <key> [--context NAME]	Remove a key
tappass config list [--context NAME] [-o table|json|toml]	Show all contexts (* marks the current one)
tappass config use-context <name>	Switch the active context
tappass config current-context	Print the active context name
tappass config delete-context <name>	Delete a context

tappass config set server https://staging.tappass.ai --context staging
tappass config set org-id acme --context staging
tappass config use-context staging

Root commands

Command	Description
tappass chat "<message>" [-m MODEL] [-a AGENT] [--org ORG] [-s SERVER] [--raw] [-v]	Send a message through the governance pipeline (same path as POST /v1/chat/completions)
tappass try "<prompt>" [-m MODEL] [--dry-run] [-v]	Run a governed agentic loop as agent cli-try: it reasons over your connected MCP tools and every tool call is governed live (allow / block / approve / shape). --dry-run governs and shows decisions but executes nothing. Works from anywhere: remote runs stream every step and verdict live over SSE
tappass init [-s SERVER] [--defaults]	Set up your organization: connect, sign in, approve tools, set security level, store provider credentials
tappass status	Diagnose your environment and connection (tappass info is an alias)
tappass ask "<question>"	Ask Jorge — the governed assistant — about your workspace (“why was this session blocked?”); the answer streams live with every tool step and verdict visible
tappass login / logout / whoami	Root shortcuts for tappass auth login/logout/whoami (see tappass auth)
tappass test [SCENARIO.yaml] [-a AGENT] [-v]	Dry-run agent calls against live policies — no real API calls
tappass providers	List available providers and their operations
tappass up [--defaults]	Guided setup: storage, runtime, secrets, migrations, start the server
tappass down	Stop the tappass/tappass-pg containers (data preserved)
tappass quickstart [-a AGENT] [-m MODEL] [-p PORT]	Zero to governed agent: server, account, agent, copy-paste code
tappass demo [basic|attack|crewai|all] [--list] [--no-seed]	Interactive demos against a TapPass instance
tappass logs [-n LIMIT] [-a AGENT]	Deprecated — use tappass audit list

tappass auth

The unified credentials group — session verbs, personal access tokens, per-agent developer keys, and scripting/SDK credentials. The everyday session verbs are also registered at the root: tappass login, tappass logout, and tappass whoami are shortcuts for tappass auth login/logout/whoami.

Command	Description
tappass auth login [--server URL] [--with-token] [--email X --password-stdin] [--google] [--saml-org SLUG]	Sign in. Default: Personal Access Token prompt (like gh auth login); --with-token reads a tp_pat_… token from stdin. --server is persisted to the active context
tappass auth logout	Sign out and clear the stored session
tappass auth whoami	Show the current identity
tappass auth session	Inspect the current session
tappass auth print-token	Print the current bearer token to stdout (nothing else) — the scripting escape hatch: curl -H "Bearer $(tappass auth print-token)" …
tappass auth application-default login	Write Application Default Credentials to ~/.tappass/application_default_credentials.json; the SDK picks them up automatically (no explicit key configuration)
tappass auth application-default revoke	Delete the Application Default Credentials file
tappass auth pat create <name> / list / revoke <id>	Personal access tokens
tappass auth developer-key list / create / delete	Per-agent developer API keys

tappass agent

Command	Description
tappass agent list [--limit N] [--cursor C] [-o table|json]	List agents in your org
tappass agent get <uuid>	Show one agent
tappass agent create [AGENT_ID] [-d DESC] [-f FRAMEWORK] [-c CAPS] [--project ID] [--directory DIR] [--no-write-env] [--from-file YAML]	Register an agent and write its .env; --from-file batch-registers from YAML (--continue-on-error to skip failures). tappass agent onboard is a deprecated alias
tappass agent suspend <uuid> / activate <uuid>	Hard stop (gateway rejects all calls) / reactivate
tappass agent pause <uuid> / resume <uuid>	Pause / resume
tappass agent update <uuid> / delete <uuid> / move <uuid>	CRUD + move between projects
tappass agent detail <uuid> / overview / policy <uuid> / sessions <uuid> / audit <uuid> / pipelines <uuid>	Drill-down views
tappass agent keys rotate <uuid> [--by-uuid]	Rotate the agent’s signing keypair; the new private key is shown once
tappass agent keys show <uuid>	Show the registered public key
tappass agent keys set-policy <uuid> --policy disabled|optional|required	Per-agent signature enforcement (required needs a registered key)

tappass audit

Command	Description
tappass audit list [--since 1h|24h|7d|30d|all] [--event-type a,b] [--action allowed,blocked,flagged] [--agent X] [--session ID] [--task ID] [--cursor C] [--limit N]	Query audit events with cursor pagination
tappass audit overview	Aggregate audit statistics
tappass audit get <event_id>	One event in full
tappass audit session <id> / task <id> / pipeline <id>	Events scoped to a session, task, or pipeline run
tappass audit show-session <event_id>	Look up an audit event and jump straight to its session detail
tappass audit replay <event_id> [--policy-overrides JSON|@file] [--pipeline-id ID]	Re-run a past event against proposed policy (always dry-run; shows baseline vs proposed decision diff)
tappass audit tail [--since 5m] [--interval N] [...filters]	Live tail; TTY shows a colored stream, piped output is JSON-lines

tappass session

list, overview, get <id>, trace <id> (span tree), baseline, similar, watch (live stream), show-policy <id>, show-audit <id>.

tappass policy

Command	Description
tappass policy create --org-id SLUG --name NAME (--from-prompt "…" [-i] | --from-rules FILE | --from-template ID [-p k=v]) [--dry-run] [-d DESC] [-o auto|table|json]	Create a policy from a described purpose (→ smallest capability envelope), a JSON file of authored rules, or pre-filled from a template. -i reviews the derived rules interactively (adjust / drop / approve) before anything persists; --dry-run previews without persisting. The single “make a policy” verb (supersedes agents govern / pack apply)
tappass policy rules list / get <id> / instantiate <id> -p k=v	Rule catalog — parameterized rule generators; instantiate renders a validated, ready-to-run policy
tappass policy floor get --org SLUG (or --project ID)	Read the org-floor / project-policy override
tappass policy floor update (--from FILE | --from-template ID -p k=v) --org SLUG (or --project ID)	Update the org floor (PUT /api/orgs/{org}/policy) or project override
tappass policy export <id> [--runtime claude_code|monty] [--stdout] [PATH]	Compile a policy’s active version into its runtime config and install it at the runtime’s standard path (merged into whatever is already there); --stdout prints instead of installing
tappass policy effective	Show the effective policy for a scope
tappass policy explain	Explain why a decision was made
tappass policy graph	Visualize policy linkage
tappass policy controls [--json]	List the authoring vocabulary rule add accepts
tappass policy rule add <agent> <control> [-p k=v] --org-id SLUG [--apply | --shadow] [--json]	Stage an agent-scoped rule, print the plan, optionally apply
tappass policy rule apply <policy_id> <version_no> --scope-id X [--scope-type agent|team|project|org] [--shadow]	Activate (or shadow-apply) a staged draft

Versions & assignments

Command	Description
tappass policy version list / create / publish / pull-back / fork / diff / rules	Version lifecycle
tappass policy assignment create / delete	Assign policies to scopes
tappass policy agent compiled <agent> / assignments <agent>	Compiled policy view and assignments for an agent

tappass template

Command	Description
tappass template list / get <id>	Curated multi-rule starter sets (OWASP agentic baseline, coding-agent safety, compliance frameworks, …) — the same catalog as Policies → Templates in the dashboard. Apply one via the dashboard or build on it with policy create

tappass approval

list, show <id>, approve <id>, deny <id>, cancel <id> — human-in-the-loop approval requests. Approve/deny can open a browser decision page.

tappass capability

Command	Description
tappass capability list [--connected] [-c CAPABILITY] [-o table|json]	Read-only tree unfolding each capability into the servers and tools that fulfil it (each tool tagged → intent). --connected limits to your connected MCPs instead of the full catalog; -c drills into one capability

tappass connector

A connector is a capability-fulfiller — an MCP server plus its tools. This one group covers the catalog, connection lifecycle, grants, and per-tool controls.

Command	Description
tappass connector catalog / list / show <name>	Browse the connector catalog
tappass connector add / approve <name> / disable <name> / refresh <name> / review <name>	Lifecycle management
tappass connector connect <name>	Connect a connector (OAuth flow)
tappass connector grant list / add / remove	Connector grants
tappass connector tool list <connector>	Tool snapshot: name / class / enabled / changed
tappass connector tool enable <connector> <tool> / disable <connector> <tool>	Toggle individual tools
tappass connector tool integrity get <agent_uuid> [--status pending|approved|all]	List MCP tool fingerprints (rug-pull detection)
tappass connector tool integrity approve <agent_uuid> --tool X --fingerprint FP (or --all -y)	Approve a fingerprint as the new baseline

tappass skill

The imported-skill registry — ingest external skills, review them, and gate which agents or teams may use them.

Command	Description
tappass skill list [--status pending|approved|denied] / show <id>	List imported skills and their review state, or show one in full
tappass skill ingest	Ingest a skill (hashed + injection-scanned); lands pending review
tappass skill ingest-plugin	Ingest every skill in a plugin directory — each scanned, pending review
tappass skill grant / revoke	Grant (or remove) skills or a whole plugin to an agent or team
tappass skill approve <id> / deny <id>	Approve a reviewed skill across the org, or deny it
tappass skill rescan <id>	Re-run the injection detectors over the stored instruction text

tappass model and tappass model key (BYOK)

tappass model list, register, test, set-price, update, archive — the org’s model registry. update edits in-place metadata (--enable/--disable, --display-name, --icon-url); set-price cuts a new price version (--cost-input/--cost-output, cost per 1k tokens).

BYOK provider keys nest under model as key: tappass model key list, get <provider>, set <provider> --key KEY (use --key @path or --key - for stdin — never leaks the raw key), rotate <provider>, delete <provider>.

Identity and org structure

Command	Description
tappass me get / update / access / sessions	Self-service account (personal access tokens moved to tappass auth pat …)
tappass org list / get / switch / current / delete	Organizations
tappass org create --name NAME [--slug SLUG] [--description D]	Create a new org (caller becomes ORG_ADMIN)
tappass org update <org-id> [--name] [--description] [--data-region]	Update org fields
tappass workspace get / update	Org-wide settings
tappass org members list / invite / remove	Org members
tappass org invitations list / revoke / resend	Pending invitations
tappass project list / get / create / update / delete / use / current	Projects (per-org)
tappass project members list / bindings list / bindings create / bindings delete	Project members + bindings
tappass team list / get / create / update / delete	Teams
tappass team members list / add / remove, team projects list	Team members + project links

Infrastructure

Command	Description
tappass db start [-p 5432] [--data .tappass/pgdata] [--name tappass-pg]	Start local PostgreSQL in Docker, run migrations, print the DATABASE_URL
tappass db migrate [--url DSN]	Run pending migrations
tappass db status / stop / destroy [-y]	Inspect / stop / destroy the local database
tappass backup create [-o FILE.tar.gz]	Backup state, policies, and provider configs
tappass backup restore <file> [--dry-run]	Restore from a backup archive
tappass backup db [-o FILE.sql]	pg_dump the database (requires pg_dump in PATH)
tappass activity list [--since …]	The governance event feed
tappass activity cube [-g DIM[,DIM]] [-f DIM=VAL] [--since 1h|24h|7d|30d] [--sort MEASURE] [-o table|json]	Aggregated, pivotable rollup of governed activity (calls / allowed / blocked / tokens / cost) — the evidence behind watch-mode policy
tappass activity params --tool KEY [--by agent|user] [--since …] [--limit N]	Latest exposure on one MCP tool: which parameters it’s called with, and by whom