CLI Quickstart

First steps

1. 1

   Set your agent key

   Create an agent in the dashboard and expose its key to the CLI as an environment variable. Secret commands exchange this key for short-lived scoped tokens automatically.

   Shell

   Copy

   # Create an agent in the dashboard, then export its key
   export ASS_AGENT_KEY="ass_xxxxxxxxxxxxxxxxxxxxxxxx"
   
   # Confirm the CLI can reach the API
   ass status
   # status   ● Operational
   # logged in  yes

   ℹ️

   Non-interactive environments

   CI/CD, Docker, and agent runtimes should set ASS_AGENT_KEYdirectly. No browser login is required for secret read/write commands.

2. 2

   List and retrieve secrets

   Browse your vault and pull secret values directly to your terminal:

   Shell

   Copy

   # List secrets in a namespace
   ass secrets list production
   # → production/gemini/GEMINI_API_KEY          sensitive   v3   2d ago
   # → production/stripe/STRIPE_SECRET_KEY       critical    v1   7d ago
   # → production/database/DATABASE_URL            standard    v2   1h ago
   
   # Retrieve a specific secret value
   ass secrets get production/gemini/GEMINI_API_KEY
   # → gemini-api-key-example
   
   # Use --json for scripting
   ass secrets get production/gemini/GEMINI_API_KEY --json
   # → {"path":"production/gemini/GEMINI_API_KEY","value":"gemini-api-key-example","version":3}

   ⚠️

   Terminal history

   Secret values printed to stdout may appear in your shell history. Pipe to a file or use --json and process programmatically to avoid accidental exposure.

3. 3

   Import your .env file

   Bulk-import an existing .env file into a namespace. Always dry-run first:

   Shell

   Copy

   # Import all secrets from .env
   ass env import .env --namespace production
   # Scanning .env...
   # ✓ Imported: production/GEMINI_API_KEY
   # ✓ Imported: production/STRIPE_SECRET_KEY
   # ✓ Imported: production/DATABASE_URL
   # ✓ Imported: production/SLACK_BOT_TOKEN
   # ✓ Imported 12 secrets to production
   
   # Preview without writing
   ass env import .env --namespace production --dry-run

4. 4

   Register your first agent

   Use the dashboard to create an agent registration with scoped access. Each service should have its own agent with the minimum required scopes:

   Shell

   Copy

   # Recommended setup in the dashboard:
   # 1. Open /dashboard/agents
   # 2. Add an agent named "my-inference-agent"
   # 3. Allow namespace: production/gemini
   # 4. Allow scopes: secrets:read:*
   # 5. Copy the generated ass_... key once
   
   export ASS_AGENT_KEY="ass_xxxxxxxxxxxxxxxxxxxxxxxx"

   🚨

   Save the agent key now

   The agent key is shown only once at creation. Copy it immediately and store it in your secrets manager. If you lose it, you'll need to revoke the agent and create a new one.