CLI Reference

The tap CLI manages credentials, agents, and roles via SQLite with encrypted credential storage (AES-256-GCM). It is primarily useful for self-hosted deployments. For managed hosting, the admin API provides the same functionality and is the recommended interface.

All management commands use --encryption-key (or AGENTSEC_ENCRYPTION_KEY env var) and --db (default ./agentsec.db).

tap add

Add a new credential to the database. Runs interactively if --name is omitted.

# Non-interactive
tap add \
  --db agentsec.db \
  --encryption-key $AGENTSEC_ENCRYPTION_KEY \
  --name slack \
  --description "Slack API" \
  --auth api-key \
  --api-base https://slack.com/api
 
# Interactive mode
tap add --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY

Flag	Default	Description
`--db`	`./agentsec.db`	SQLite database path
`--encryption-key`	`$AGENTSEC_ENCRYPTION_KEY`	64 hex chars for AES-256-GCM
`--name`	(interactive)	Credential name
`--description`	(interactive)	Human-readable description
`--auth`	(interactive)	Auth type: `api-key`, `oauth2`, `oauth1`, `custom`
`--api-base`	(interactive)	API base URL or sidecar URL
`--relative-target`	`false`	Target is a relative path (for protocol translators)

Auth type mapping:

Auth type	Connector	Default `api_base`
`api-key`	`direct`	user-provided
`oauth2`	`sidecar`	`http://oauth2-refresher:8081`
`oauth1`	`sidecar`	`http://oauth-signer:8080`
`custom`	`sidecar`	user-provided

tap status

Check proxy health.

tap status [--proxy-url http://localhost:3100]

Flag	Default	Description
`--proxy-url`	`http://localhost:3100`	Proxy URL to health-check

tap logs

Display formatted audit log entries from the JSON lines file.

tap logs [--log-file ./audit.jsonl] [--tail 20]

Flag	Default	Description
`-l, --log-file`	`./audit.jsonl`	Path to audit log
`-t, --tail`	`20`	Number of recent entries (0 = all)

Agent Management

tap agent list

List all agents with their status.

tap agent list --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY

tap agent create

Create a new agent. Generates an API key and prints it once.

tap agent create \
  --db agentsec.db \
  --encryption-key $AGENTSEC_ENCRYPTION_KEY \
  --name my-agent \
  --description "My research agent" \
  --roles reader,writer \
  --credentials slack \
  --rate-limit 100

Flag	Description
`--name`	Agent identifier (required)
`--description`	Human-readable description
`--roles`	Comma-separated role names to assign
`--credentials`	Comma-separated direct credential names
`--rate-limit`	Max requests per hour (omit for unlimited)

tap agent show

Show agent details and effective permissions (union of roles’ credentials and direct assignments).

tap agent show --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY my-agent

tap agent enable

Re-enable a disabled agent.

tap agent enable --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY my-agent

tap agent disable

Disable an agent. All requests from this agent will be rejected.

tap agent disable --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY my-agent

tap agent delete

Delete an agent.

tap agent delete --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY my-agent

Role Management

Roles provide RBAC for credential access. An agent’s effective permissions are the union of all its roles’ credentials plus its direct credential assignments.

tap role list

tap role list --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY

tap role create

tap role create \
  --db agentsec.db \
  --encryption-key $AGENTSEC_ENCRYPTION_KEY \
  --name reader \
  --description "Read-only access" \
  --credentials slack,github \
  --rate-limit 50

tap role add-credential

Grant a credential to a role.

tap role add-credential \
  --db agentsec.db \
  --encryption-key $AGENTSEC_ENCRYPTION_KEY \
  reader slack

tap role remove-credential

Revoke a credential from a role.

tap role remove-credential \
  --db agentsec.db \
  --encryption-key $AGENTSEC_ENCRYPTION_KEY \
  reader slack

tap role delete

Delete a role. Cascades — removes the role from all agents that have it.

tap role delete --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY reader

Proxy API Policies & Approval