CLI Reference
Complete reference for every ass command, flag, and example.
Global flags
All commands accept --json where machine-readable output is supported. Set ASS_AGENT_KEY for non-interactive secret commands andASS_API_URL for self-hosted installs.
Authentication
ass loginLegacy credential storage for human user credentials. Agent runtimes should set ASS_AGENT_KEY directly.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --key <key> | string | — | Credential to store without an interactive prompt |
Example
export ASS_AGENT_KEY="ass_xxxxxxxxxxxxxxxxxxxxxxxx"
ass secrets list production
# Secret commands exchange the agent key for scoped tokens automaticallyass logoutRemove saved credentials from the local config file.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --profile <name> | string | — | Log out of a specific profile |
| --all | boolean | false | Log out of all profiles |
Example
ass logout
# ✓ Logged out. Config cleared from ~/.config/ass/config.jsonass whoamiDisplay tenant details for a human user token. Agent keys are intended for secret commands.
Example
ass whoami
# you@example.com
# Plan: Pro
# Secrets: 47
# Agents: 3ass statusCheck connectivity to the Agent Secret Store API and show vault health.
Example
ass status
# API
# url https://api.agentsecretstore.com
# status ● Operational
#
# AUTH
# logged in yesSecrets
ass secrets list [namespace]List all secrets in a namespace. Omit namespace to list the default namespace.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --json | boolean | false | Output as JSON |
Example
ass secrets list production
# production/gemini/GEMINI_API_KEY api_key sensitive 2d ago
# production/stripe/STRIPE_SECRET_KEY api_key critical 7d ago
# production/database/DATABASE_URL db_credential standard 1h agoass secrets get <path>Retrieve the value of a secret. Prints the plaintext value to stdout.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --json | boolean | false | Output full metadata as JSON |
| --silent | boolean | false | Suppress all output except the value |
Example
ass secrets get production/gemini/GEMINI_API_KEY
# gemini-api-key-example
# JSON output
ass secrets get production/gemini/GEMINI_API_KEY --json
# {"path":"production/gemini/GEMINI_API_KEY","value":"gemini-api-key-example","version":3}ass secrets set <path> <value>Create or update a secret. Increments the version if the path already exists.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --tier <tier> | string | standard | Secret tier: standard | sensitive | critical |
| --type <type> | string | custom | Secret type: api_key | oauth_token | db_credential | ssh_key | certificate | custom |
Example
ass secrets set production/gemini/GEMINI_API_KEY "gemini-api-key-example" \
--type api_key \
--tier sensitive
# ✓ Secret stored at production/gemini/GEMINI_API_KEYass secrets delete <path>Soft-delete a secret and revoke matching tokens. Requires confirmation.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --force | boolean | false | Skip confirmation prompt |
Example
ass secrets delete production/gemini/GEMINI_API_KEY
# Delete production/gemini/GEMINI_API_KEY? [y/N] y
# ✓ Secret deleted: production/gemini/GEMINI_API_KEYass secrets rotate <path>Rotate a secret: stores the new value as the next version while preserving history.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --value <value> | string | — | Replacement secret value |
| --force | boolean | false | Skip confirmation prompt |
Example
ass secrets rotate production/gemini/GEMINI_API_KEY --value "gemini-new-key-example"
# ✓ Secret rotated: production/gemini/GEMINI_API_KEYEnvironment
ass env import <file>Bulk-import a .env file into a namespace. Secret names are derived from variable names.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --namespace <ns> | string | — | Target namespace (required) |
| --dry-run | boolean | false | Preview without writing |
Example
ass env import .env --namespace production
# ✓ Imported 12 secrets to productionass env export <namespace>Export all secrets in a namespace to a .env file.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --output <file> | string | — | Write to file instead of stdout |
Example
ass env export production --output .env.local
# ✓ Exported 12 secrets to .env.localAgents
ass agents listList all registered agents in your vault.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --json | boolean | false | Output as JSON |
Example
ass agents list
# ID NAME STATUS CREATED
# agt_7f3a9b2c my-inference-agent active 3d ago
# agt_1a2b3c4d data-pipeline-agent active 1w agoass agents createRegister a new agent with scoped access. Requires a human user credential.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --name <name> | string | — | Agent name for non-interactive creation |
| --description <description> | string | — | Optional agent description |
| --namespace <namespaces> | string | — | Comma-separated allowed namespaces |
| --scopes <scopes> | string | — | Comma-separated allowed scopes |
Example
ass agents create \
--name my-inference-agent \
--description "Gemini inference worker" \
--scopes "secrets:read:production/gemini/*"
# API Key: ass_xxxx ← save this!ass agents revoke <agent-id>Revoke an agent, immediately invalidating its agent key and all issued tokens.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --force | boolean | false | Skip confirmation |
Example
ass agents revoke agt_7f3a9b2c
# ✓ Agent agt_7f3a9b2c revoked. All tokens invalidated.Tokens
ass tokens issueIssue a scoped, short-lived token for an agent or pipeline step.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --scopes <scopes> | string | — | Comma-separated permission scopes (required) |
| --ttl <ttl> | string | 1h | Token lifetime, e.g. 15m, 1h, 24h |
| --max-uses <n> | number | — | Maximum successful uses before the token burns |
| --ip-allowlist <ips> | string | — | Comma-separated IP addresses or CIDR ranges |
Example
ass tokens issue \
--scopes "secrets:read:production/gemini/*" \
--ttl 30m
# eyJhbGciOiJIUzI1NiIs...
# Expires: 2026-06-02T12:30:00ZApprovals
ass approvals listList pending approval requests.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --status <status> | string | — | Filter: pending | approved | denied | expired |
| --json | boolean | false | Output as JSON |
Example
ass approvals list --status pending
# ID AGENT TIER STATUS REQUESTED
# 00000000-0000 11111111-1111-... sensitive pending ○ 5m agoass approvals approve <id>Approve a pending approval request.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --force | boolean | false | Skip confirmation prompt |
Example
ass approvals approve 00000000-0000-4000-8000-000000000123
# ✓ Approved: 00000000-0000-4000-8000-000000000123ass approvals deny <id>Deny a pending approval request.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --reason <text> | string | — | Denial reason (required) |
| --force | boolean | false | Skip confirmation prompt |
Example
ass approvals deny 00000000-0000-4000-8000-000000000123 --reason "Not authorized for this key"
# ✓ Denied: 00000000-0000-4000-8000-000000000123Audit
ass auditView recent audit log entries.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --limit <n> | number | 25 | Number of entries to show |
| --tail | boolean | false | Follow new entries in real time |
| --json | boolean | false | Output as JSON |
Example
ass audit --limit 10
# 2026-06-01 10:30:01 secret.read production/gemini/GEMINI_API_KEY
# 2026-06-01 10:28:44 token.issued secrets:read:production/gemini/*
# 2026-06-01 09:15:22 secret.updated production/database/DATABASE_URL
# Follow live
ass audit --tailUtilities
ass initInitialize Agent Secret Store in the current project. Creates an .assrc config file.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --namespace <ns> | string | — | Default namespace for this project |
Example
ass init --namespace production
# ✓ Created .assrc in current directory
# ✓ Added .assrc to .gitignoreass openOpen the Agent Secret Store dashboard in your browser.
Example
ass open
# Opening https://agentsecretstore.com/dashboard ...Environment variables
All CLI flags can be set via environment variables — useful for CI/CD and Docker:
| Variable | Equivalent flag | Description |
|---|---|---|
| ASS_AGENT_KEY | — | Agent key for secret commands |
| ASS_NAMESPACE | — | Default namespace for secrets commands |
| ASS_API_URL | — | Override API base URL (for self-hosted installs) |