aihabitat-cli — Habitat for Linux

A headless command-line client for Habitat. Log in, run your agents (Codex / Claude Code) routed through Habitat, manage your wallet, and invoke managed capabilities — all from a terminal or SSH session. No GUI, no Electron.

npm i -g aihabitat-cli
habitat login
habitat               # interactive dashboard (TUI)
habitat agent run claude

What it does

• Account — password login with refresh-token rotation; the session and your default API key are stored 0600 under ~/.config/habitat.
• Agents — one-click install / configure / run / update for Codex, Claude Code, OpenClaw, and Hermes. habitat agent run <agent> installs it if needed, points it at the Habitat gateway, and opens it in your current terminal. (Codex/Claude install from npm; OpenClaw from npm into ~/.openclaw/runtime; Hermes via its official installer — needs python3.)
• Wallet — balance, vitals (burn rate / runway), recharge-code redemption, ledger and recharge history.
• Skills — invoke Habitat's managed capabilities (image generation, audio transcription, wallet vitals) with just your API key.
• Dashboard — run habitat with no arguments for an interactive, keyboard-driven terminal dashboard (balance, agents, wallet, skills) in the Habitat aesthetic — works over SSH.
• Agent integration — habitat mcp is a Model Context Protocol server that exposes Habitat's capabilities as tools, so Claude Code, Codex, Cursor, and other MCP clients can call Habitat directly.

Commands

Interface
  (no command) | ui                                   Launch the interactive dashboard (TUI)

Account
  login [-i <email|phone>] [-p <password>]            Log in
  logout                                              Clear local session + key
  whoami                                              Show the logged-in account

Agents (codex · claude · openclaw · hermes)
  agent ls                                            List agents + install status
  agent run <agent> [-m <model>] [-- <args>]          One-click: install + configure + open
  agent install <agent>                               Install an agent
  agent setup <agent> [-m <model>]                    Install (if needed) + configure
  agent update [<agent>|--all]                        Update agent(s)
  agent uninstall <agent>                             Remove an agent
  agent bind <agent> [-m <model>]                     Point an agent at Habitat
  agent doctor                                        Diagnose runtime + routing

Wallet
  wallet balance                                      Wallet balance
  wallet vitals                                       Balance / burn rate / runway
  wallet ledger [-n <limit>]                          Recent ledger entries
  wallet history [-n <limit>]                         Recharge history
  redeem <code>                                       Redeem a recharge code

Skills
  skill ls                                            List managed capabilities
  skill invoke <id> [--arg k=v]... [-m <model>] [--json]

Agent integration
  mcp                                                 Run the MCP server (Claude Code / Codex / Cursor)
  mcp config                                          Print the MCP registration snippet

Config
  config                                              Show config
  config set api-base-url <url>                       Set the API base URL
  config --profile <prod|local>                       Switch base-URL profile
  config set-model <agent> <model>                    Set an agent's default model

Examples

# First run on a fresh server
npm i -g aihabitat-cli
habitat login -i [email protected]
habitat agent install claude
habitat agent run claude          # Claude Code, routed through Habitat, in this TTY

# Top up with a recharge code, then check vitals
habitat redeem HABITAT-7Q4K-9XZP
habitat wallet vitals

# Generate an image via a managed capability (just needs your API key)
habitat skill invoke habitat.image.generate --arg prompt="a red panda" --arg size=1024x1024

# Pass flags through to the underlying agent
habitat agent run codex -- --help

How routing works

• Codex — bind/run writes ~/.codex/config.toml (model_provider = "habitat", provider base_url = <api>/v1, wire_api = "responses") and your real sk-habitat- key into ~/.codex/auth.json. Codex talks directly to Habitat; it keeps working after the CLI exits. Existing config keys are preserved.
• Claude Code — run launches claude with ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN injected into the process environment (any ambient ANTHROPIC_* is stripped so Habitat's routing wins). No file is written and your ~/.claude config is untouched.

Environment

| Variable | Purpose | |---|---| | CLAW_HABITAT_API_BASE_URL | Override the API base URL (default https://api.aihabitat.live) | | HABITAT_CLI_CONFIG_DIR | Override the config/secret dir (default $XDG_CONFIG_HOME/habitat) | | OPENCLAW_STATE_DIR | Override the managed-agent install dir (default ~/.openclaw) | | OPENCLAW_NPM_REGISTRY | Pin the npm registry used to install agents | | HTTPS_PROXY / HTTP_PROXY | Forwarded to npm when installing agents | | NO_COLOR | Disable colored output |

Security

Credentials are stored in ~/.config/habitat/secrets.json with 0600 permissions (the same posture as gh, aws, and the codex CLI's own auth.json). This is a deliberate, documented downgrade from the desktop app, which encrypts secrets with the OS keychain. A keyring backend is planned.

Development

npm run typecheck   # tsc --noEmit
npm run test        # node --test (no network)
npm run build       # tsup → dist/cli.js (self-contained, bundles @habitat/shared)
npm run dev -- <args>

Scope

MVP: password login, agent install/run (Codex + Claude, direct-key), wallet balance/vitals/redeem, and capability invoke. Planned: card recharge (Alipay/Stripe order + poll), verification-code login, an opt-in loopback proxy, and version-policy-gated self-update.