clara (packages/cli)

Published on npm as @quiknation/clara-cli (binary clara): voice greeting and POST /voice/converse loop by default. Full terminal IDE: clara tui.

Env (voice default): CLARA_VOICE_URL (quikvoice base), optional CLARA_VOICE_API_KEY (Bearer).

Feature flags: CLARA_FEATURE_INTENT_DISPATCH=1 (or true) — when set, clara doctor also probes POST /api/v1/run (backend intent dispatch); until that ships, expect intent_gateway_pending (501).

Gateway cognitive verbs use POST /v1/run only (unified intent shape). If unified dispatch is not available (404 / 501 / intent_gateway_pending), the CLI errors with a clear “unified intent dispatch is not available” message — there is no legacy POST /v1/<verb> fallback.

Usage

npm install -g @quiknation/clara-cli@latest

After installation, the clara binary is on your PATH.

Auth (clara login)

1. Run clara login. The CLI starts an HTTP server on 127.0.0.1 (random port) and opens https://claracode.ai/cli-auth?cli_port=<port> in the browser.
2. After you complete sign-in on the site, the page must POST to http://127.0.0.1:<port>/ with JSON:

{
  "email": "[email protected]",
  "sessionToken": "<Clerk session JWT>",
  "apiKey": "cc_live_… or sk-clara-…"
}

(session_token / api_key are accepted as aliases.) Credentials are stored without the keytar native addon: on macOS via security (generic password, service clara-code, account default); on Linux via secret-tool when libsecret is available; otherwise in ~/.clara/credentials with mode 0600. A legacy plaintext credentials file, if present, is migrated into the native store when possible and removed. clara auth login is a hidden alias of the same flow. clara doctor reports credential availability, whether GET /health on the resolved backend succeeds, ~/.clara/last-error.json when written by a failed command, and (when signed in) GET /api/v1/tier-status (tier and billing cycle end).

Commands

| Command | Description | |--------|-------------| | clara (no args) | Plays the canonical greeting, then Space twice for push-to-turn audio over /voice/converse | | clara --version | Print the CLI version | | clara login | Browser sign-in; store session + API key in the credential store (see Auth above) | | clara doctor | Check credential storage, credentials, Heru-style layout (when present), parallel reachability to gateway / brain / backend, tier status (/api/v1/tier-status, cached to ~/.clara/tier-status-cache.json) when logged in, optional POST /api/v1/run when CLARA_FEATURE_INTENT_DISPATCH=1. --scope limits checks (all default, scaffold, endpoints, auth, tier) | | clara greet | Request Clara's voice greeting from the API and play the audio | | clara config get <key> | Print resolved gatewayUrl, brainUrl, backendUrl, userId, or apiKey (credential store) | | clara config set <key> <value> | Set a allowed key: URLs / userId in ~/.clara/config.json; apiKey via the credential store (native Keychain / secret-tool, or the private ~/.clara/credentials file — never in config.json) | | clara config list | Show each key, resolved value, and source (env / config / default / credential store) | | clara config unset <key> | Remove a file-stored override or clear apiKey in the credential store (session token kept) | | clara config-agent | Interactive harness agent setup — POST /api/v1/run intents config_agent.templates / config_agent.configure (same data as /api/agents/templates + /configure). Option: --backend. (configure-agent alias) | | clara new <name> | Local Heru folder from the gateway: POST /v1/run (intent: new, heru_name) with a file diff applied under ./<name>/. Options: --dry-run, --force, --gateway. If the platform returns a Git URL only, use clara init instead. | | clara wire-auth --clerk | Plus+ — gateway applies Clerk wiring into the current directory (POST /v1/run, intent: wire-auth). Options: --name, --dry-run, --force, --gateway. | | clara verify-brain | Ask the platform to run a canary against the brain for this Heru (POST /v1/run, intent: verify-brain). Options: --name, --query, --json, --gateway. | | clara init <name> | Create a per-agent GitHub repo via POST /v1/run (intent: new) when the gateway returns cloneUrl / repoUrl, then git clone into ./<name>/ (Business/Enterprise tier). Options: --gateway. Failures write ~/.clara/last-error.json for clara doctor. | | clara deploy [backend\|frontend] | Backend (default): POST /v1/run (intent: deploy). Frontend: runIntent("deploy.frontend", { target, env }) (no local wrangler/aws). Options: --gateway, --name, --backend (ignored for backend deploy), and for frontend --target cloudflare\|amplify, --env develop\|production. | | clara provision-brain | Cook+ — runIntent("provision-brain"); optional --dry-run, --force, --region. Writes ~/.clara/<heru>/brain.json when the gateway returns brain_url + ssm_key_path. | | clara attach-talent [name] | Plus+ — attach / --list / --remove. Gateway owns Talent IP. | | clara talent new <name> | Cook+ — interactive authoring (runIntent("talent.new")); optional --from-file, --non-interactive (stdin JSON). Registry draft is server-side only. | | clara gear add <name> | Plus+ — runIntent("gear.add"); --force, --config-file. eas-attestation: --staging, --schema-id. voice-clone: consent (type yes), live --voice-sample / --from-file. Prints inbound email when the gateway returns it. Slugs: email-receiver-cf, eas-attestation, voice-clone. | | clara gear remove <name> | Plus+ — runIntent("gear.remove"). | | clara gear list | Plus+ — installed Gears for this agent; --json. | | clara gear catalog | Plus+ — marketplace catalog; --json. | | clara gear test <name> | Plus+ — runIntent("gear.test"); --staging for EAS; prints explorer URL when returned. | | clara smoke daysha | Cook+ — runIntent("smoke.daysha") (long timeout). Receipt under ~/.clara/, --keep, --no-cleanup-on-failure, --json. | | clara chat | Same streaming Ink experience as clara tui (preferred alias) | | clara tui | Full-screen Ink TUI: gateway chat, VRD Surface C copy, Ctrl+Space voice, --voice placeholder |

Quickstart

clara --version
clara config set apiKey YOUR_API_KEY
clara greet
clara tui --gateway https://your-gateway.example.com

TUI

Text-first by default; optional --voice for future audio when the gateway supports it.

• Ctrl+Q quit (saves session hint to ~/.clara/config.json)
• Ctrl+M toggle mic UI (recording placeholder; use typed input for messages)
• Enter send

Gateway default matches clara config get gatewayUrl when nothing is set: https://api.claracode.ai/hermes (override with CLARA_GATEWAY_URL or clara config set gatewayUrl <url>). The directory ~/.clara/ is created when you first write config.

Development

From the repository root:

cd packages/cli
npm install
npm run build
node dist/index.js tui

CLI

clara tui
clara tui --user mo --gateway https://your-gateway.modal.run
clara --help

Config

~/.clara/config.json (no apiKey or inference keys in the file — model / system_prompt / temperature are rejected; use clara login for session, clara config set apiKey for credential-store-only keys).

{
  "gatewayUrl": "https://your-gateway.example.com",
  "brainUrl": "https://brain-api.claracode.ai",
  "userId": "your-name",
  "lastSessionDate": "2026-04-10",
  "lastProject": "my-app",
  "sixSideProjectsAsked": true
}