codealmanac CLI — current vs final

Every command, mapped from today's local-first tool to the hosted-first model. Generated from the live command registrars in src/cli/.

Local — read

Operates on the .almanac/ files already in your repo checkout. No account, no network. The wiki is your repo's files.

Hosted — build

You trigger; hosted runs the engine server-side and commits .almanac/ back into the repo via the GitHub App. Needs login.

Local lab

The developer-experimentalist path: run the engine on your machine with your provider + sessions. Opt-in, explicit.

hosted = the WRITER · git / repo = the MEDIUM (where .almanac/ lives) · local = the READER
Reading never touches the API — by the time there's anything to read, hosted has written it into your repo and you've pulled it.

new command that does not exist today now hosted, backend already supports it later hosted, needs backend work first moves same engine, relocated to the lab zone same behaviour essentially unchanged

Local — reading no login

These read the .almanac/ in your checkout. This is the correction: today these already run locally, and they must stay local — never proxy to the hosted API.

Command	Current	Final
`search [query]`	FTS over local `index.db`; `--mentions`, `--topic`, `--since`, `--stale`, `--orphan`, `--json`, `--slugs`.	Unchanged. Reads the repo's `.almanac/` off disk. same
`show [slug]`	Print a page (metadata + body; `--lead`, `--backlinks`, `--links`, `--stdin`…).	Unchanged. Reads `.almanac/pages/<slug>.md` on disk. same
`serve`	Local read-only console on `127.0.0.1:3927`.	Unchanged. Browses local files. same
`topics list` `topics show`	List / inspect the topic DAG from the local index.	Unchanged (read side). The edit verbs move to the lab. same
`health`	8-category graph-integrity report over local pages.	Stays local — a read-only diagnostic over your repo's wiki. same
`reindex`	Force-rebuild `.almanac/index.db`.	Stays — it's the read cache for `search`/`show`. Mostly implicit. same
`list`	List wikis in the local `~/.almanac/registry.json`.	Folds into hosted `repos`. Local registry stays an internal detail for resolving the current repo. moves

Hosted — build & runs login

The assumed center. You trigger work; hosted runs the engine and commits the wiki back into your repo. Expose the small now set first; add the rest one by one.

Command	Current	Final
`login`	—	Browser GitHub-OAuth flow; backend issues a CLI token to a localhost callback; stored in `~/.codealmanac/auth.json`. new needs token endpoint
`logout`	—	Clear the stored CLI token. new
`whoami`	—	`GET /me` — logged-in user + default account. new now
`use <account>`	—	Select the current org/account; repo defaults to the cwd's git remote. new now
`repos` `repos <repo>`	—	List connected repos / show one (access, wiki present?). `GET /accounts/{id}/repositories`, `GET /repositories/{id}`. new now
`build`	`init` builds the wiki locally via your agent.	Triggers a hosted build run; result is delivered back into the repo. Today triggering happens in the UI only — the CLI trigger comes after delivery is settled. new later
`runs` `runs <id>`	Hosted activity was invisible to the CLI (only local `jobs`).	List / watch hosted runs. `GET /repositories/{id}/runs`, `GET /runs/{id}`, poll for `--watch`. new now
`absorb <inputs…>` `ingest`	Updates the wiki locally from files/PRs/issues/URLs via your agent.	Triggers a hosted absorb run from a source. Backend run-with-source path doesn't exist yet. later
`garden`	Maintains structure/links/topics locally via your agent.	Triggers a hosted garden run. No hosted garden endpoint yet. later
`sources`	—	List / inspect / exclude captured conversation sources attached to runs. Whole capture feature is still research. new later
`settings`	—	View / change repo settings. `PATCH /…/settings` exists; just unsurfaced. new later

Local lab — run the engine yourself opt-in

The developer-experimentalist surface. Same engine, executed on your machine with your provider keys and your own Claude/Codex sessions. Off by default; explicitly enabled in setup. A logged-in user never runs these by accident — local execution is a deliberate switch.

Command	Current	Final
`init --local`	`init` = the default, local build.	Build the wiki locally with your agent. The default `build` is hosted; `--local` is the lab. moves
`absorb --local`	Default behaviour, local.	Local absorb from explicit sources, your agent/keys. moves
`garden --local`	Default behaviour, local.	Local graph maintenance, your agent/keys. moves
`sync` `sync status`	Scan local Claude/Codex transcripts, absorb new material locally.	Stays as the local-transcript path. The hosted equivalent is conversation capture (separate, later). moves
`automation install` `uninstall` / `status`	macOS launchd jobs running scheduled local `sync`/`garden`.	Lab-only. Hosted "automation" is the GitHub App running on PRs — no CLI command needed. moves
`jobs list/show/logs/attach/cancel`	Records of local background runs.	Stays for local lab runs. Hosted activity is the new `runs` command. moves
`agents list/doctor/use/model`	Pick / diagnose the local provider (Claude, Codex, Cursor) the engine runs.	Only relevant when running the engine locally → lab. Hosted needs no local agent. moves
`tag` / `untag`	Deterministic frontmatter topic edits.	Manual local edits → lab/power-user. Hosted maintains topics itself. moves
`topics create/link/unlink/ rename/delete/describe`	Deterministic DAG edits, rewriting page frontmatter.	Local lab edits. (`topics list/show` remain in the read zone.) moves
`review add/list/show/ decide/apply/reopen`	Local review-escalation records.	Lab. In the hosted product, review happens in the PR diff. moves
`migrate legacy-sources` `migrate automation`	Deterministic one-off local migrations.	Lab / maintenance utility. moves

System — setup & diagnostics

Install, posture, config, self-update. The big change is setup flips from "assume local author" to a posture chooser.

Command	Current	Final
`setup`	Installs scheduled automation + agent guides; assumes you're a local author (picks a provider, installs the scheduler).	Posture chooser: default = reading installed (nothing runs); offer Connect to Cloud (`login`) and Enable local lab (provider + automation). States why the lab exists. moves
`doctor`	Install + current-wiki health.	Reports posture: logged in? connected repo? lab enabled? + local read health. same
`config list/get/set/unset`	Local settings (provider, automation, auto-commit…); assumes local-author defaults.	Posture-aware: reader = ~empty; hosted = auth + selected account/repo; lab = provider/automation. A bare install writes ~nothing. moves
`update`	Foreground `npm i -g`; `--check`, `--dismiss`.	Unchanged — keep the binary current. same
`uninstall`	Remove automation + guides + CLAUDE.md import.	Remove guides + lab automation; also `logout`. same

The v1 we actually ship first (the small section): login · logout · whoami · use · repos · runs on the hosted side (read + identity), with reading (search/show/serve) untouched and local. build and the rest stay later — triggering is UI-only today, and the bigger blocker is settling delivery (how/where the wiki lands), not the command itself. The only hard prerequisite for the read CLI is the token endpoint behind login.