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>Move a secret and all its versions to trash and revoke matching tokens. Requires confirmation. Undo with ass secrets restore.
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 moved to trash: production/gemini/GEMINI_API_KEY
# Undo with: ass secrets restore production/gemini/GEMINI_API_KEYass secrets trashList deleted secrets you can restore. Needs a human login (ass login).
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --json | boolean | false | Output as JSON |
Example
ass secrets trash
# PATH VERSIONS TIER DELETED
# production/gemini/GEMINI_API_KEY 3 sensitive 5m agoass secrets restore <path>Restore a deleted secret with all its versions. Fails if a live secret already uses the path.
Example
ass secrets restore production/gemini/GEMINI_API_KEY
# ✓ Secret restored: production/gemini/GEMINI_API_KEY version 3ass secrets history <path>List the versions of a secret, newest first. Values are never shown.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --json | boolean | false | Output as JSON |
Example
ass secrets history production/gemini/GEMINI_API_KEY
# VERSION TIER CREATED
# v3 sensitive 1h ago current
# v2 sensitive 2d ago
# v1 standard 9d agoass secrets rollback <path> <version>Make an earlier version current again. It is saved as a new version, so history is kept. The access tier is never lowered.
Example
ass secrets rollback production/gemini/GEMINI_API_KEY 1
# ✓ Rolled back production/gemini/GEMINI_API_KEY v1 is now current as v4ass 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 register --eid <did>Sign an agent up with its OpenEntity DID, with no account. Signs the vault challenge with `npx openentity present` and prints the agent key and a claim URL for the owner.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --name <name> | string | — | Agent name shown to the owner |
| --openentity-home <dir> | string | — | Directory with the agent's OpenEntity identity and key (sets OPENENTITY_HOME) |
| --presentation <file> | string | — | Use a Presentation you already signed for this challenge |
Example
ass register --eid did:key:z6Mk… --name research-bot
# ✓ Vault created
# export ASS_AGENT_KEY=ass_…
# https://agentsecretstore.com/claim?code=ABCD-EFGH-JKLMass 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 |
| --eid <did> | string | — | OpenEntity DID to bind; unverified until `ass agents verify-eid` |
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 verify-eid <agent-id>Prove the agent controls its OpenEntity DID. Requests a single-use challenge, signs it with `npx openentity present`, and submits the Presentation.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
| --openentity-home <dir> | string | — | Directory with the agent's OpenEntity identity and key (sets OPENENTITY_HOME) |
| --presentation <file> | string | — | Use a Presentation you already signed for this challenge |
Example
ass agents verify-eid agt_7f3a9b2c
# ✓ EID verified: did:key:z6Mk…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) |