CLI commands

Every command obeys the interactive-vs-non-interactive rule: a TTY gets a TUI; flags-only gets a non-interactive flow with --json where applicable.

Every command runs against the current project (found by walking up from cwd looking for config.yml). Errors fast if no project is found and the command needs one.

Command	Status	Purpose
init [name]	✓ M2	Scaffold a project + pick a model
wiki generate [name]	🚧 M3	LLM wiki creation (per data/ file)
wiki list	🚧 M4	List articles
wiki show <name>	🚧 M4	Print one article
wiki edit <name>	🚧 M4	Open $EDITOR on wiki/<name>.md
build [flags]	🚧 M5	Package the project into a zip; optional upload
chat [question]	🚧 M6	Terminal REPL (or one-shot)
serve	🚧 M8	Run the embedded dashboard + /api/* server
import <source>	🚧 M9	Download + install a share zip
eval [flags]	🚧 M14	LLM-as-judge eval (dev-time; requires internet)
doctor	✓ M2	Health check

No share, get, demo, or skills command. Skills live in skills/ and are loaded automatically at chat time.

local-agents (no args)

Welcome screen. Lists the next 3 commands to try. Idempotent.

Welcome to local-agents.

First time?           local-agents init my-handbook
Got a share zip?      local-agents import <url>
Build your own:       cd my-project && local-agents wiki generate

local-agents init [name]

✓ Shipped (M2). Quickstart →

local-agents init my-handbook                # interactive picker (TTY)
local-agents init my-handbook --yes          # accept the top-ranked model
local-agents init my-handbook --model gemma-4-e4b-q4_k_m
local-agents init                            # scaffold in CWD
local-agents init my-handbook --manifest https://my.mirror/manifest.json
local-agents init my-handbook --parent-dir /tmp/projects

What it does:

1. Fetch the manifest from llama-cpu-benchmarks.
2. Verify schema + tool-calling floor.
3. Pick a model (interactive picker, or --yes / --model).
4. Scaffold the project folder.
5. Write model.id to config.yml.
6. Download GGUF + ONNX to ~/.config/local-agents/ (sha256 verified, cache-hit short-circuit).
7. Print a next-steps hint.

local-agents doctor

✓ Shipped (M2).

local-agents doctor                    # pretty terminal table
local-agents doctor --json             # machine-readable
local-agents doctor --port 8088        # check a different port
local-agents doctor --project /path    # override project root

Eight checks: config.yml load+validate, model.gguf presence, embedding presence, free disk space (Statfs on unix / GetDiskFreeSpaceEx on windows), port availability, every commands[].run binary on PATH, every skill runtime: on PATH, eval API key presence if eval: is configured.

Exits 1 if any check has severity error.

local-agents wiki generate [name]

🚧 Stub (M3). Spec'd shape:

local-agents wiki generate                   # all data/ files
local-agents wiki generate return-policy     # one article
local-agents wiki generate --force           # ignore `frozen: true`
local-agents wiki generate --dry-run         # preview prompts; write nothing

The same wiki-instructions.md template can be fed to claude-code manually — drop the output into wiki/<name>.md and build doesn't care which path produced it.

local-agents wiki list / show / edit

🚧 Stub (M4).

local-agents wiki list                       # all articles + types
local-agents wiki show oncall                # print wiki/oncall.md
local-agents wiki edit oncall                # opens $EDITOR

local-agents build

🚧 Stub (M5).

local-agents build                                  # → ./my-handbook.zip
local-agents build --out ./dist/my-handbook.zip
local-agents build --self-contained                 # bundle model (~3-5 GiB)
local-agents build --to s3://bucket/key.zip         # upload instead of writing
local-agents build --to https://upload.example      # PUT to URL
local-agents build --self-contained --to s3://...   # both
local-agents build --no-smoke-test                  # skip demo-question smoke

By default runs every demo: question through the full chat pipeline as a smoke test before sealing the zip.

local-agents chat [question]

🚧 Stub (M6).

local-agents chat                            # streaming REPL
local-agents chat "question?"                # one-shot
local-agents chat --no-rag                   # disable RAG tool
local-agents chat --no-skills                # disable skills

local-agents serve

🚧 Stub (M8). Binds 127.0.0.1 by default. No auth.

local-agents serve                           # localhost:8080
local-agents serve --port 8088
local-agents serve --host 0.0.0.0 --allow-public

local-agents import <source>

🚧 Stub (M9/M10).

local-agents import ./my-handbook.zip            # local file
local-agents import https://share.example/x.zip  # URL
local-agents import s3://bucket/x.zip            # S3 (ambient AWS_*)
local-agents import URL --to ./other-name
local-agents import URL && cd my-handbook && local-agents serve

local-agents eval

🚧 Stub (M14). Dev-time only — requires internet + a big-model API key (ANTHROPIC_API_KEY, OPENAI_API_KEY).

local-agents eval                     # run tests/test-set.yml, judge it
local-agents eval --generate          # synthesize a test set from data/
local-agents eval --id <scenario-id>  # run one scenario
local-agents eval --no-judge          # scenarios; print outputs; skip scoring
local-agents eval --json              # machine-readable result

Exits non-zero if mean score < eval.pass_threshold (default 7.0/10).