@arial-ai/cli

Command-line interface for Arial — the agentic product analytics tool.

Designed agent-first: every command emits structured output with explicit next-step instructions, making it usable by coding agents (Claude Code, Cursor, etc.) and by humans alike.

Install

npm install -g @arial-ai/cli
# or
npx @arial-ai/cli --help

Requires Node.js 20 or newer.

Quick start

# 1. Create a fresh workspace and receive an agent key
arial signup --name "My Project"

# 2. The agent key is saved to ~/.config/arial/config.json by default.
#    Verify it works:
arial whoami

# 3. Share the claim URL printed by `signup` with the human owner,
#    or have them run:
arial workspace claim <passphrase>

Commands

arial signup [--name <name>] [--no-save]   Create a workspace + agent key (unauthenticated)
arial login  [--key <key>] [--api-url <url>]  Save an API key for future commands
arial logout [--purge]                      Remove the stored API key
arial whoami                                Print the authenticated user

arial workspace list                        List workspaces visible to the current key
arial workspace show <slug>                 Show one workspace
arial workspace signup [--name ...]         Alias of `arial signup`
arial workspace claim <passphrase>          Claim a workspace as the current user

arial taxonomy list                         List canonical events shipped with Arial
arial taxonomy show <event>                 Show schema + properties + example
arial taxonomy context                      Show the universal context fields

Agent-friendly output

All commands accept --json for a stable envelope:

{
  "status": "ok" | "error",
  "command": "workspace.signup",
  "summary": "...",
  "data": { ... },
  "next_steps": [{ "action": "...", "command": "...", "reason": "...", "priority": "primary" }],
  "errors": [{ "code": "...", "message": "...", "hint": "..." }],
  "warnings": ["..."],
  "resources": [{ "label": "Docs", "url": "https://arial.sh/docs" }]
}

Exit codes:

| Code | Meaning | | ---- | ----------------- | | 0 | Success | | 1 | Unknown error | | 2 | Unauthorized | | 3 | Not found | | 4 | Validation error | | 5 | Network error |

Configuration

Settings are resolved in this order (later overrides earlier):

1. ~/.config/arial/config.json (or $XDG_CONFIG_HOME/arial/config.json)
2. Env vars: ARIAL_AGENT_KEY, ARIAL_API_URL
3. Command-line flags (--key, --api-url)

Set ARIAL_CONFIG_DIR to override the config location entirely.

License

MIT