aihabitat-cli 2026.625.0

package/README.md

@@ -0,0 +1,125 @@
+# `@habitat/cli` — Habitat for Linux
+
+A headless command-line client for [Habitat](https://aihabitat.live). 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.
+
+```bash
+npm i -g @habitat/cli
+habitat login
+habitat agent install claude
+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** — installs the official `@openai/codex` and `@anthropic-ai/claude-code`
+  CLIs into a managed dir (`~/.openclaw/agent-clis`), points them at the Habitat
+  gateway, and runs them in your current terminal.
+- **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.
+
+## Commands
+
+```
+Account
+  login [-i <email|phone>] [-p <password>]            Log in
+  logout                                              Clear local session + key
+  whoami                                              Show the logged-in account
+
+Agents
+  agent ls                                            List agents + install status
+  agent install <codex|claude>                        Install an agent CLI
+  agent update [<codex|claude>|--all]                 Update agent CLI(s)
+  agent uninstall <codex|claude>                      Remove an agent CLI
+  agent bind <codex|claude> [-m <model>]              Point an agent at Habitat
+  agent run <codex|claude> [-m <model>] [-- <args>]   Run an agent in this terminal
+  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]
+
+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
+
+```bash
+# First run on a fresh server
+npm i -g @habitat/cli
+habitat login -i alice@example.com
+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
+
+```bash
+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.