@sechroom/cli 2026.7.32 → 2026.8.1

package/README.md

@@ -1,295 +1,59 @@
-# sechroom-cli (Route 1 skeleton)
+# Sechroom CLI
 
-A thin **npm-distributed** CLI over the Sechroom HTTP API. A deliberate
-alternative agent/human surface to MCP — and because the agentic coding tools
-(Claude Code, Codex, Cursor) drive CLIs by reading `--help` and parsing stdout,
-every command emits clean JSON via `--json`.
-
-## Why this shape (grounded in the backend, verified against source)
-
-- **One contract.** OpenAPI is served at `/openapi/v1.json` (`Program.cs`:
-  `AddOpenApi()` + `MapOpenApi()`) — the same doc the UI's
-  `frontend/packages/api-client` and Bruno consume. The CLI generates its
-  client from it; there is no hand-maintained request/response surface.
-- **The API is the real surface.** Every MCP tool is a thin shim over a
-  Wolverine handler that is _also_ a `[WolverinePost]`/`[WolverineGet]` endpoint
-  carrying the same `[TenantPermission]`. The permission middleware is HTTP-only,
-  so the CLI inherits identical enforcement.
-- **Tenant is mandatory.** `MapWolverineEndpoints` calls `TenantId.AssertExists()`
-  — a missing `tenant` header is a hard 400. The client sets it on every request.
-- **Auth matches the AS.** `OAuthEndpointMappings.cs` exposes auth-code + PKCE
-  (`/oauth/authorize` -> `/oauth/token`), RFC 8414 discovery, and RFC 7591
-  dynamic client registration (`/oauth/register`). No device-code or
-  client-credentials grant — so the CLI uses the loopback auth-code + PKCE
-  pattern and self-registers via DCR, mirroring how Claude.ai web connects.
-  Headless/CI sets `SECHROOM_TOKEN`.
-
-### Verified specifics that shaped the code
-
-- **DCR `client_id` is deterministic** (`RegisterClientEndpoint.cs`):
-  `dyn-` + base64url(SHA256(sorted `redirect_uris`))[:22], idempotent on the
-  redirect set. PKCE-only, no secret. The CLI therefore registers a **fixed set
-  of candidate loopback ports** as the redirect_uris (stable set -> stable id)
-  and binds whichever is free — so re-login never mints a new client or stales
-  the cache.
-- **PKCE is S256-only** (`TokenEndpoint.VerifyPkce`).
-- **Refresh works** (`TokenEndpoint`): `grant_type=refresh_token` is a real
-  grant, and the token body returns a `refresh_token` for non-browser clients.
-  `requireToken()` refreshes automatically near expiry.
-- **`POST /memories`** binds `CreateMemoryInput` — `Content` and `Confidence`
-  are required (MCP shim defaults `"{}"` / `1.0`); `Owner` is nullable (omit for
-  Unfiled). The `create` command applies those defaults.
-- **`GET /memories/{memoryId}`** returns an `OperationsItem<MemoryReadModel>` envelope.
-- **`POST /memories/search`** (`SearchMemoriesEndpoint`) — `SemanticQuery`
-  routes to the hybrid vector+FTS RRF ranker; the `search` command uses it.
+The Sechroom CLI lets you sign in, wire your AI tools, and work with your sechroom from the terminal. Every command supports `--json` for scripts and agent workflows.
 
 ## Install
 
 ```bash
-# pre-GA / internal builds are published under the `next` dist-tag
-npx @sechroom/cli@next login
-npm i -g @sechroom/cli@next
+# Install globally
+npm i -g @sechroom/cli
 
-# once GA (promoted to `latest`)
-npx @sechroom/cli login
+# Run without installing
+npx @sechroom/cli
 ```
 
-## Develop
+Node.js 20 or later is required.
 
-This is a **pnpm workspace member** (`frontend/apps/cli`). Install from the repo root
-(`pnpm install`), then run scripts via the filter (or `pnpm <script>` from this dir):
-
-```bash
-pnpm --filter @sechroom/cli run gen          # regenerate the typed client
-pnpm --filter @sechroom/cli run check-types
-pnpm --filter @sechroom/cli run build
-pnpm --filter @sechroom/cli run dev -- --help # tsx, no build
-```
+## Get started
 
-## Generate the client (once, and after any API change)
+For guided setup, run:
 
 ```bash
-# defaults to https://app.sechroom.ai/api/openapi/v1.json
-pnpm --filter @sechroom/cli run gen
-SECHROOM_OPENAPI_URL=https://<host>/api/openapi/v1.json pnpm --filter @sechroom/cli run gen   # other envs
+sechroom onboard
 ```
 
-`gen` overwrites `src/generated/api.d.ts`. The **real generated types are
-committed** (regenerated from the live prod spec) so builds are hermetic — no
-live-API dependency at compile time; re-run `gen` after any API change. Generating
-against the live schema is what caught the original placeholder's shape drift
-(e.g. the work-log append body is `{bullet, laneId, workspaceId, title}`, and
-`CreateMemoryInput`/`SearchInput` require several nullable fields present), now
-fixed in the command bodies.
-
-## Use
+To configure the CLI manually:
 
 ```bash
-sechroom config set baseUrl https://app.sechroom.ai/api      # prod (staging: https://staging.app.sechroom.ai/api)
-sechroom config set tenant  ocd
+sechroom config set baseUrl https://app.sechroom.ai/api
+sechroom config set tenant <your-tenant>
 sechroom login
-
-sechroom memory create --text "first note from the CLI" --type reference
-sechroom memory get mem_XXXX
-sechroom memory search "convention lifecycle drift" --limit 5
-sechroom worklog append --text "shipped CLI skeleton; pointers: ..." --source claude-code-chris
-
-sechroom lookup mem_XXXX                 # what is this id? -> kind / title / view URL
-sechroom lookup sechroom:mem_XXXX --json # namespaced form also resolves
-
-sechroom --json memory get mem_XXXX     # agent-friendly
-```
-
-**Output shape.** Mutating commands (`memory create`, `worklog append`) print a concise confirmation line — id + view URL — the way the MCP tools hand an LLM a result, instead of dumping the raw envelope. Pass `--json` for the full response body (the machine channel) on any command. Output is lightly colorized on a TTY and auto-plain when piped, under `--json`, or when `NO_COLOR` is set.
-
-```bash
-sechroom memory create --text "a note" --title "Note"
-# ✓ created memory mem_XXXX "Note" → https://sechroom.yi.ocd.codes/view/mem_XXXX
-```
-
-**Per-directory config.** A project dir can pin its own `tenant` + `baseUrl` in a local `.sechroom.json`, discovered by walking **up** from cwd (nearest wins, so any subdir inherits it). It overrides the global config — precedence: `--flag` > env > directory-local > global > default. `clientId` / auth state stays global.
-
-```bash
-sechroom config set --local tenant  cli-smoke                       # this dir + subdirs
-sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
-sechroom config show                                                # resolved values + which source won
-```
-
-**Smoke testing.** There is a dedicated **`cli-smoke`** tenant on **both staging and prod** for exercising the CLI without touching real tenants — point at staging and use it:
-
-```bash
-sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
-sechroom config set --local tenant  cli-smoke
-sechroom login
-sechroom worklog append --text "cli smoke" --source claude-code-chris
-```
-
-Headless:
-
-```bash
-export SECHROOM_TOKEN="<bearer: a PAT or dev-token JWT>"
-export SECHROOM_TENANT=ocd
-sechroom --json memory search "rate limiting"
 ```
 
-## Executor channel migration
-
-`sechroom channel` now consumes the generic executor advertisement and claims a
-durable exact-instance offer before forwarding work. Configure the checkout once,
-then install the channel entry:
+## Everyday commands
 
 ```bash
-sechroom executor install --connector <approved-connector-id>
-sechroom channel install
+sechroom memory create --text "Project kickoff notes" --title "Project kickoff"
+sechroom memory get mem_XXXX
+sechroom memory search "project decisions" --limit 5
+sechroom lookup mem_XXXX
+sechroom worklog append --text "Prepared the release notes" --source terminal
 ```
 
-The former `channel --workspace ... --tag ...` shape is retired. Those options are
-accepted for one compatibility release and print a deprecation warning, but they
-no longer participate in eligibility or reconnect recovery. Running `channel
-install` rewrites the managed `.mcp.json` entry without them. Workspace authority,
-capabilities, runtime profiles, instance identity, and lane affinity now come from
-the installed executor state plus server-side persona/connector resolution.
-
-Reconnect recovery reads durable offers for the exact executor instance; it no
-longer queries a workspace memory feed. Existing unmanaged channel entries should
-remove `--workspace`, `--tag`, and `--executor-instance` after the executor harness
-has been installed.
-
-## Command surface (MCP parity)
-
-The CLI mirrors the sechroom MCP tool surface — every command is a thin wrapper over the same HTTP endpoint the matching MCP tool shims, so enforcement (`[TenantPermission]`) is identical. Run `sechroom <group> --help` for the subcommands + examples.
-
-| Group                | Covers                                                                                                                                                           |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `memory`             | create / get / search · edit-text(+batch) · archive / restore / move · versions / revert · list-archived · owners / tags / types · sum-tokens · similar · by-url |
-| `relationship`       | create / list / delete · suggest · `suggestion` get / accept / reject / defer                                                                                    |
-| `workspace`          | create / list / get · rename / describe / move · archive / restore · feed                                                                                        |
-| `project`            | create / list / get · rename / describe / move · status · victory-conditions · archive / restore                                                                 |
-| `filing`             | suggestions / get · preview · accept / reject / defer / edit-and-accept                                                                                          |
-| `continuity`         | snapshot-create / -get · snapshots · resume-me / resume-lane · changed-since · load-set · grant / revoke-grant                                                   |
-| `id`                 | next / peek (FR-_/D-_ sequence allocation)                                                                                                                       |
-| `account`            | profile / set-profile · feed · reviews / review-get / review-accept · lookup-batch                                                                               |
-| `chat`               | send · messages · replies · stop-tracking (Slack / Discord, via `--surface`)                                                                                     |
-| `worklog` · `lookup` | append · resolve any id                                                                                                                                          |
-
-Notes on deliberate gaps (API-rooted, not CLI):
-
-- **No `memory delete`** — the API exposes no hard DELETE; `memory archive` is the soft-delete path.
-- **`memory revert`** needs `--text` + `--content` — the revert endpoint doesn't reconstruct a version's body from its number; pull them from `memory versions` / `memory get` first.
-
-## Onboarding (`init` / `setup`)
-
-`sechroom init` wires a project for sechroom by rendering the server's
-operator-surface setup descriptors (`GET /operator-surface/setup`, tenant-scoped
-— the aggregator URL is baked in) into local AI-client config + agent instruction
-files. **Idempotent — merges/appends, never clobbers** (JSON `mcpServers` merge;
-Codex TOML table replace; instruction files use a managed marker block).
+Add `--json` when you need machine-readable output:
 
 ```bash
-sechroom init                       # Claude Code (default): .mcp.json + CLAUDE.md
-sechroom init --client all          # claude-code, claude-desktop, codex, cursor
-sechroom init --client codex,cursor # a subset
-sechroom init --mcp-only            # just the MCP config (skip agent files)
-sechroom init --dry-run --json      # preview the writes, no changes
-
-# granular pieces init orchestrates:
-sechroom setup mcp claude-desktop          # just the MCP config for one client
-sechroom setup agent-files codex           # just the AGENTS.md instruction file
+sechroom --json memory search "project decisions"
 ```
 
-### `sechroom onboard` — guided first run
-
-`onboard` orchestrates the whole zero-to-wired path interactively: configure base
-URL + tenant, sign in, set the profile timezone, then wire your AI client(s). Two
-prompts make it fit how you actually work:
+## Headless use
 
-- **Where to save config** — globally (`~/.config/sechroom`, all projects) or a
-  directory-local `.sechroom.json` (this project + subdirs). Defaults to local
-  when a `.sechroom.json` already governs the dir.
-- **How far to wire** — full (MCP server + agent instructions), agent
-  instructions only (skip `.mcp.json`), or **CLI only** (write nothing for AI
-  clients — for when you just want the `sechroom` command).
+Set a bearer token and tenant in the environment when browser login isn't available:
 
 ```bash
-sechroom onboard                    # interactive: asks where to save + how to wire
-sechroom onboard --cli-only         # just the CLI — no .mcp.json, no agent files
-sechroom onboard --no-mcp           # agent instructions only, skip MCP config
-sechroom onboard --local            # save tenant + base URL to ./.sechroom.json
-sechroom onboard --yes              # non-interactive: defaults + global config + full wire
+SECHROOM_TOKEN=<bearer-token> SECHROOM_TENANT=<your-tenant> sechroom --json memory search "project decisions"
 ```
 
-Per client → where it writes:
-
-| client           | MCP config                             | instruction file      |
-| ---------------- | -------------------------------------- | --------------------- |
-| `claude-code`    | `./.mcp.json`                          | `./CLAUDE.md`         |
-| `claude-desktop` | `claude_desktop_config.json` (OS path) | `~/.claude/CLAUDE.md` |
-| `codex`          | `~/.codex/config.toml`                 | `./AGENTS.md`         |
-| `cursor`         | `./.cursor/mcp.json`                   | `./AGENTS.md`         |
-
-The instruction-file step pulls the role template the SEM Starter bundle ships
-(via the descriptor's tag-query artifact). If that bundle isn't installed in the
-tenant, the step **skips gracefully** with a note (MCP config still gets written).
-
-## Layout
-
-```
-src/
-  index.ts            commander root + global flags + login/config
-  auth.ts             OAuth auth-code+PKCE loopback (fixed-port DCR) + refresh + cache
-  client.ts           openapi-fetch client (auth + tenant middleware) + emit/fail
-  config.ts           base-url / tenant / token resolution + persistence
-  generated/api.d.ts  typed client — `pnpm run gen`; real types committed (hermetic)
-  commands/
-    memory.ts         create / get / search / edit / archive / move / versions / …
-    relationships.ts  relationships + relationship-suggestions
-    workspace.ts      workspace CRUD + feed
-    project.ts        project CRUD + status / victory-conditions
-    filing.ts         filing-suggestion review (accept / reject / defer / edit-and-accept)
-    continuity.ts     snapshots + resume / grant
-    account.ts        id next/peek + profile / feed / reviews / lookup-batch
-    chat.ts           read Slack / Discord messages + replies
-    worklog.ts        append
-    lookup.ts         resolve any id (mem_…/unprefixed/sechroom:<id>) -> kind/title/url
-    setup.ts          init + setup mcp/agent-files
-  setup/
-    operator-surface.ts  fetch GET /operator-surface/setup + resolve template artifacts
-    clients.ts           client→(surface, local paths, format) registry
-    apply.ts             writers: mcp json merge / codex toml / instruction marker block
-```
-
-## Remaining before ship
-
-- **Provision the npm publish credential** (the only blocker): create the
-  `@sechroom` npmjs org + an Automation token and paste it into the
-  `Sechroom_PublishCli` build config's `NPM_TOKEN` param. See
-  [`ci/PUBLISHING.md`](./ci/PUBLISHING.md).
-- Decide the registered candidate-port set (`CANDIDATE_PORTS` in `auth.ts`) —
-  three localhost ports today; keep them stable, since the DCR client id is a
-  function of that set.
-
-## Distribution (initial)
-
-Public **npmjs** under the `@sechroom` org is the host; **TeamCity** is the
-publisher (build config `Sechroom_PublishCli`). The full pipeline — steps,
-parameters, npm auth, provisioning, and how to run a publish — is documented in
-[`ci/PUBLISHING.md`](./ci/PUBLISHING.md). In short: a manual-trigger config runs
-`pnpm install → gen → check-types → build → publish` (filtered to `@sechroom/cli`)
-in a `node:20` container, authed by a masked `NPM_TOKEN` param. Every publish gets a
-fresh calendar version `YYYY.M.<n>` (own counter); the dist-tag separates next/latest.
-
-Why public npmjs: the CLI is customer-facing, and `npx @sechroom/cli` must work
-with zero `.npmrc`/token on the customer side. GitHub Packages or a private
-registry would force every external adopter to authenticate just to install.
-
-Pure Node — no runtime prerequisite beyond Node 20. If a zero-dependency single
-binary is later preferred, the alternative is per-platform AOT binaries published
-as npm `optionalDependencies` behind a launcher shim (the esbuild/biome pattern),
-at the cost of an OS×arch build matrix. This (plain Node) keeps install friction
-lowest.
-
-## Onboarding hook
+## More commands
 
-Parallels `BuildMcpConfigSection` in `OperatorSurfaceDescriptors`: a
-`BuildCliConfigSection` can emit the `npx @sechroom/cli` invocation + the
-`config set` bootstrap the same way the MCP config is surfaced today.
+Run `sechroom --help` for the full command list, or `sechroom <group> --help` for group-specific options and examples.