@anima-labs/cli

Official command-line interface for Anima — identity infrastructure for AI agents. Email, phone, voice, vault, addresses, and a unified policy engine — one CLI, one identity per agent.

Install

npm install -g @anima-labs/cli

That's it. Run anima onboard to authenticate and walk through the agentic-commerce flow end-to-end.

Tell your agent to set you up

In Claude Code, Cursor, Codex, or any MCP-aware agent:

Read useanima.sh/skill.md and get me set up with Anima

The agent reads the skill manifest, installs the CLI, wires up Anima's MCP servers, and finishes onboarding for you.

MCP servers

Run anima setup-mcp install --all to wire every supported client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) automatically. The default remote mode points clients at the hosted gateway (https://mcp.useanima.sh/mcp, Bearer-authenticated); pass --mode stdio to run the @anima-labs/mcp server locally via npx instead.

To wire a client manually, point it at the hosted gateway in .mcp.json:

{
  "mcpServers": {
    "anima": {
      "type": "http",
      "url": "https://mcp.useanima.sh/mcp",
      "headers": {
        "Authorization": "Bearer ak_your_api_key"
      }
    }
  }
}

Alternative installs

bun add -g @anima-labs/cli           # bun
brew install anima-labs/tap/anima    # homebrew (macOS / Linux)
npx @anima-labs/cli init             # try without installing

Output: agent vs human

By default every command prints agent format — compact single-line JSON, ~30-40% smaller than pretty JSON, machine-parseable. Pass --human for a pretty terminal view.

anima email list                 # agent default: {"emails":[…]}
anima email list --human         # ┌── box-drawn table
anima email list --format yaml   # explicit yaml
anima email list --format jsonl  # one record per line

Primary binary: anima. Short alias: am.

Command Reference

auth — Authentication and session management

anima auth login          # Authenticate with Anima
anima auth logout         # Clear stored credentials
anima auth whoami         # Show current org, agent, and how each was resolved

Some operations — creating an agent, rotating keys, anima tail — need admin rights that the agent key from anima init does not carry. There is no command to run first: those commands step up on demand, and macOS asks for your login password.

The first step-up emails a code to the organization owner and enrols this machine, inline, at the moment you need it. Enrolment stores a grant in your keychain behind a human-presence gate, so later step-ups need no email — just the password prompt. Admin access lasts for the one command that asked for it and is never written down, so each one prompts.

An agent driving the CLI holds the API key and can run every command, but it cannot answer a system password dialog. That is the boundary. Note the gate is local: it governs release of the grant on this machine, and the server cannot verify a human was present.

Enrolment is macOS-only. Elsewhere the CLI refuses to store a grant rather than pretend it is protected, and every step-up keeps using the emailed code.

Enrolment needs an interactive terminal once, because the code has to be typed back in. A CI job or an agent driving am fails with that explanation rather than blocking on a prompt nothing will answer.

agent — Manage agents

anima agent create        # Create a new agent (in your current org)
anima agent list          # List agents
anima agent use <id>      # Set the default agent for later commands
anima agent get <id>      # Get agent details
anima agent update        # Update agent properties
anima agent delete        # Delete an agent
anima agent rotate-key    # Rotate the agent's API key
anima agent did           # Get the agent's DID document
anima agent credentials   # List the agent's verifiable credentials
anima agent card          # Get the public agent card

Previously anima identity. Both identity and the short id still work as aliases, so existing scripts are unaffected.

email — Send and manage emails

anima email send          # Send an email
anima email list          # List received emails
anima email get <id>      # Get email details
anima email search <query>             # Full-text search over your emails
anima email search <query> --semantic  # Meaning-based (embedding) search

# Filter by label (repeat --label to require ALL); spam is hidden by default.
# Relabel a message with `anima message label <id>` (see below).
anima email list --label unread                 # unread mail only
anima email list --label unread --include-spam  # include spam-flagged
anima email search <query> --label unread       # combine text + label (full-text only)

email draft — Compose now, send later

anima email draft create  # Create a draft (may be incomplete — only --agent required)
anima email draft list    # List drafts
anima email draft get <id>     # Get draft details
anima email draft send <id>    # Send: converts the draft to a real message
anima email draft delete <id>  # Delete a draft without sending

email domains — Custom domain management

anima email domains add       # Add a custom domain
anima email domains list      # List configured domains
anima email domains get       # Get domain details
anima email domains verify    # Verify domain DNS records
anima email domains dns       # Show required DNS records
anima email domains deliverability  # Check deliverability status
anima email domains delete    # Remove a domain

inbox — Manage email inboxes

anima inbox create        # Create an inbox (--username, --domain, --display-name, --agent)
anima inbox list          # List inboxes
anima inbox get <id>      # Get inbox details
anima inbox update <id>   # Update display name or agent association
anima inbox delete <id>   # Delete an inbox

phone — Manage phone numbers and SMS

anima phone search        # Search available phone numbers
anima phone provision     # Provision a new phone number
anima phone list          # List provisioned numbers
anima phone release       # Release a phone number
anima phone send-sms      # Send an SMS message

message — Manage messages across all channels

anima message list        # List messages (email, SMS, MMS)
anima message get <id>    # Get message details
anima message search <q>  # Full-text search messages
anima message label <id>  # Add/remove labels on a message

# Labels are an agent's workflow state. System labels: unread, read,
# archived, spam. Adding `read` clears `unread` (and vice versa).
anima message label <id> --add read              # mark read
anima message label <id> --add archived --remove unread
anima message label <id> --add urgent            # your own tag

# Filter list/search by label (repeat --label to require ALL). Spam is
# hidden by default; --include-spam surfaces it.
anima message list --label unread --label urgent
anima message list --include-spam
anima message search <q> --label unread

vault — Manage password vault credentials

anima vault provision     # Provision vault for an identity
anima vault deprovision   # Remove vault from an identity
anima vault status        # Check vault status
anima vault sync          # Sync vault data
anima vault store         # Store a credential
anima vault store --generate-password  # Store a login with a vault-generated password
                          # (generated server-side, stays in the vault, only the
                          #  credential ref is returned; --length/--no-special etc.)
anima vault get           # Retrieve a credential
anima vault list          # List all credentials
anima vault search        # Search credentials
anima vault delete        # Delete a credential
anima vault generate      # Generate a password
anima vault totp          # Generate TOTP code

config — Manage CLI configuration and profiles

anima config set <key> <value>   # Set a config value
anima config get <key>           # Get a config value
anima config list                # List all config values
anima config profile list        # List profiles
anima config profile use <name>  # Switch to a profile
anima config profile clear       # Stop using any profile (back to top-level config)
anima config profile delete <n>  # Delete a profile

setup-mcp — Configure MCP server for AI clients

anima setup-mcp install   # Install MCP config for a client
anima setup-mcp uninstall # Remove MCP config
anima setup-mcp status    # Check MCP integration status
anima setup-mcp verify    # Verify MCP server connectivity

extension — Manage Anima Chrome extension

anima extension status                       # Check extension status
anima extension connect                      # Mint a headless connect URL (agent key)
anima extension connect --agent <id>         # Master key: agent is required
anima extension connect --agent <id> --ttl 15m  # Shorten the token TTL (15m | 1h | session)

extension connect returns a connectUrl to open in a Puppeteer-driven browser (plus agentId, policy, and expiry timestamps with --json). With an agent API key the agent is resolved automatically; with a master key, pass --agent.

admin — Organization and team administration

anima admin org list          # List organizations
anima admin member invite     # Invite a team member
anima admin member role       # Update member role
anima admin key rotate        # Rotate org API key
anima admin key revoke        # Revoke an API key
anima admin usage             # View usage statistics

webhook — Manage webhooks

anima webhook create      # Create a webhook
anima webhook list        # List all webhooks
anima webhook get <id>    # Get webhook details
anima webhook delete <id> # Delete a webhook
anima webhook test <id>   # Send a test event to a webhook
anima webhook deliveries <id>  # List webhook delivery history

webhook create also takes advanced settings — endpoint auth (in addition to the X-Anima-Signature HMAC) and a delivery throttle:

anima webhook create \
  --url https://example.com/hooks/anima \
  --events message.received,message.sent \
  --auth-config '{"type":"bearer","token":"whsec_..."}' \
  --rate-limit-per-minute 120 \
  --max-attempts 5

security — Security monitoring and scanning

anima security events     # List security events
anima security scan <content>  # Scan content for security threats

init — Set up Anima CLI

anima init                         # Interactive setup wizard
anima init --non-interactive \     # Scripted setup
  --api-key ak_... \
  --org my-org

Configuration

The CLI reads configuration in this priority order:

1. CLI flags (--token, --api-url, --json, --debug)
2. Environment variables (ANIMA_API_URL, ANIMA_API_KEY, ANIMA_DEFAULT_ORG, ANIMA_DEFAULT_IDENTITY, ANIMA_OUTPUT_FORMAT)
3. Active profile (set via anima config profile use <name>, cleared with anima config profile clear)
4. Default config (set via anima config set or anima init)

--org and --agent fall back through the same order, so once anima init has written a default you rarely pass either. A command that names another agent (anima a2a send --agent) still requires it: defaulting a destination to yourself would succeed at the wrong thing.

Configuration files are stored in:

• macOS: ~/Library/Preferences/anima/
• Linux: ~/.config/anima/
• Windows: %APPDATA%/anima/

Global Flags

| Flag | Description | |------|-------------| | --json | Output results as JSON | | --debug | Enable debug output | | --token <token> | API token (overrides stored auth) | | --api-url <url> | API base URL (overrides stored config) |

Building from Source

# Install dependencies
bun install

# Run in development
bun run dev -- <command>

# Build standalone binary
bun run build

# Run tests
bun test

# Type check
bun run typecheck

Community

Join the Anima Discord to ask questions, share what you're building in #showcase, and stay up to date with releases in #announcements.

License

MIT - see LICENSE

Links

• Documentation
• Discord
• GitHub
• Issues
• Anima Platform