@higherdev/cli 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+# hd
+
+HigherDEV in your terminal. Full control of the board, and live views of agents,
+tickets, runs, and spend without a browser.
+
+## Install
+
+```bash
+pnpm --filter @higherdev/cli build
+cd apps/cli && npm link      # puts `hd` on your PATH
+hd login                     # six-digit code, emailed
+hd connect                   # connect Codex to your ChatGPT subscription
+hd use test                  # pick a workspace
+hd                           # the live dashboard
+```
+
+Or from the registry: `npm i -g @higherdev/cli`, then the same commands.
+`hd upgrade` updates it, `hd upgrade --check` only reports.
+
+## Which HigherDEV
+
+`hd` is not tied to one deployment. On first sign-in it fetches the Supabase
+settings from the app's `/api/config` and caches them in
+`~/.config/higherdev/config.json`.
+
+```bash
+hd login --app-url https://dev.yourcompany.com
+```
+
+Switching deployments clears the previous one's session, cached settings, and
+selected workspace, so two never mix. `HIGHERDEV_APP_URL` overrides per command,
+and `HIGHERDEV_SUPABASE_URL` plus `HIGHERDEV_PUBLISHABLE_KEY` skip the fetch
+entirely. `HIGHERDEV_CONFIG_DIR` keeps a second deployment in its own directory
+if you work across two.
+
+Who may sign in is the deployment's decision, not the CLI's: `hd` asks the
+server's own `is_allowlisted()`, the same function RLS enforces with, so a
+published binary carries no list of names.
+
+## How it talks to the platform
+
+It signs in as you, with the same emailed six-digit code the web app uses, and
+talks to Supabase directly under RLS. No service key lives on your laptop, and
+every write records an audit event naming you, so a CLI change reads the same as
+a click. Live views are Realtime subscriptions, not polling.
+
+## Two ways to talk to it
+
+`hd ask` reaches the **orchestrator**, which runs on the box and is in charge of
+getting work in flight to finish. Ask it why something is stuck or tell it to
+reshuffle a workstream. It cannot change agent settings, and that is enforced by
+its action schema rather than by its prompt.
+
+```bash
+hd ask "why is HD-12 stuck?"
+hd msg HD-12 --to builder "also rename the old column" --interrupt
+```
+
+`hd plan` runs the **architect** here on your machine, on Codex against your
+ChatGPT subscription. It reads the repo, decides what should be built, files an
+epic, and can tune the platform itself: models, effort, routing notes, prompt
+addenda, conventions, budgets. Creating an epic fires `epic.created`, which the
+orchestrator already triggers on, so the handoff needs no glue.
+
+```bash
+hd connect                                 # ChatGPT OAuth, once per machine
+hd doctor                                  # what a run would cost, before it runs
+hd plan "assess the call-intel code and plan what is missing"
+hd plan --read-only "what would you change about the agent lineup?"
+hd plan --resume "split the third ticket, it is too big"
+```
+
+### The subscription is checked, not assumed
+
+The platform runs on subscriptions, never per-token APIs, so `hd plan` **refuses
+to start** unless Codex is signed in through the ChatGPT OAuth flow. It reads
+`~/.codex/auth.json` and distinguishes four states: connected, signed in with an
+API key (which bills per token), signed out, and not installed. `hd connect`
+runs `codex login` for you, which opens the browser and writes the token itself.
+`hd` never sees or stores a Codex credential.
+
+`--allow-api-billing` overrides the refusal when you actually mean to spend.
+
+`hd mcp` is the same platform as MCP tools on stdio. `hd plan` attaches it to
+Codex for the invocation, with no global config edit. Attach it to Claude Code or
+give Mel the read-only half:
+
+```bash
+hd mcp --list                 # the 24 tools, with what each does
+hd mcp --read-only            # safe to hand to anything
+```
+
+## Everything else
+
+```
+hd                    live dashboard          hd new "title" --area web/auth
+hd status             one-screen summary      hd set HD-12 --agent Codex
+hd board              kanban by status        hd block HD-12 HD-9
+hd ls --stuck         why nothing is moving   hd take HD-12 / hd handback HD-12
+hd show HD-12         one ticket in full      hd cancel HD-12 / hd kill HD-12
+hd watch HD-12        live run transcript     hd epic new "title" spec.md
+hd logs <run> -f      one run, following      hd epic replan <id>
+hd agents             live agent state        hd orchestrate
+hd feed               live activity           hd decide <id> "answer"
+hd inbox              decisions and messages  hd pause / hd resume [--all|-p claude]
+hd cost               spend, by day and more  hd agent set Codex --model gpt-5.6-sol
+hd hosts              runner health           hd conventions --edit
+hd connect --check    Codex connection        hd upgrade [--check]
+hd epic show <id>     dependency waves        hd attach HD-12 shot.png
+```
+
+Every read takes `--json` and every write is non-interactive when given flags, so
+Claude Code and Mel can drive the board over SSH. Colour follows `NO_COLOR` and
+turns itself off when stdout is not a terminal.
+
+## Onboarding a new host
+
+`hd init` still does host onboarding: it writes the runner env file, registers
+the host, installs the launchd plist, and checks each provider CLI is authed. It
+delegates to the runner package, so the box's systemd service never pulls in the
+CLI's UI dependencies.
+
+```bash
+hd init --host seb-mac --owner-email sebastian@higherops.io --install-launchd
+hd login
+```
+
+## Development
+
+```bash
+pnpm --filter @higherdev/cli dev -- status   # run from source
+pnpm --filter @higherdev/cli test
+pnpm --filter @higherdev/cli typecheck
+```
+
+`HIGHERDEV_CONFIG_DIR` points the config and session somewhere else, which is
+how to keep a scratch login separate from your real one.