> ## Documentation Index > Fetch the complete documentation index at: https://metalworks.lab2a.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every metalworks CLI command — by sub-app, with invocations, flags, and which need provider keys. The `metalworks` console script is CLI-first by design: `metalworks --help` and `metalworks version` work on a bare install with no extras. Everything heavier (provider SDKs, duckdb, redditwarp, the MCP server) is lazy-imported inside the command that needs it. Secrets come from the **environment only** — never the config file. The chat provider is auto-resolved by which key is present (`ANTHROPIC_API_KEY` > `OPENAI_API_KEY` > `GOOGLE_API_KEY`/`GEMINI_API_KEY`), then the keyless **`claude-code`** floor when `metalworks[claude-code]` is installed and no key is set. Commands flagged **(chat key)** below need a model — which now includes the keyless Claude Code login; the rest are **zero-key**. See [Run on your Claude Code login](/docs/configuration#run-on-your-claude-code-login-no-api-key). ## Top-level commands | Command | Description | Keys | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | | `metalworks` | **Interactive menu** — the easiest way in. Pick what to do: validate an idea, configure models / data sources, view-or-edit config, run diagnostics (`doctor`), onboard (`setup`), or browse past runs. Everything is reachable with no project and no idea. | zero-key to open | | `metalworks start` | Jump straight to **validating an idea** end to end: sets up a project if needed, asks for your idea, runs demand → landscape → assess with the **GO/PIVOT/NO-GO call in your hands** each round, then offers positioning / build spec once it earns a GO. | chat key | | `metalworks setup` | Interactive onboarding: detect provider keys, pick a model, choose sources, scaffold a project, warm embeddings. `--yes` accepts every default non-interactively. | zero-key | | `metalworks version` | Print the installed metalworks version. | zero-key | | `metalworks preflight` | **Proactive setup + update check** — is everything ready to run? Reports the active corpus reader, resolved models, extras, keys, setup issues, and a cached PyPI update check. `--json` emits the `PreflightReport`. The skills run this first. | zero-key | | `metalworks doctor` | Report installed extras, configured keys, the **resolved chat + embedding models**, the active corpus reader, the store path, connected Reddit accounts, and actionable hints (renders from the same checks as `preflight`; keeps `--fix`). | zero-key | | `metalworks init` | Create a `.metalworks/` project in the cwd (like `git init`) — a `project.json` manifest, a `config.toml`, a gitignored `corpus.db`, and a `.env.example`. Idempotent. | zero-key | **`metalworks init`** option: `--idea TEXT` — one line on what you're building (seeds the project slug). > **New to metalworks?** Just run `metalworks` with no arguments — the interactive > menu lets you validate an idea, configure models/sources, or run diagnostics > without memorizing the command chain below. `models`, `sources`, and `config` also > open their own interactive menu when run with no sub-command. ## models Inspect and set the chat/fast/embedding models. | Command | Description | Keys | | ---------------------------------- | --------------------------------------------------------------------------------------- | -------- | | `metalworks models list` | Resolved chat / fast / embedding models + a provider × key × extra reachability matrix. | zero-key | | `metalworks models set ` | Set the default chat model (writes `model` to the cwd `metalworks.toml`). | zero-key | | `metalworks models set-fast ` | Set the fast/triage model (`fast_model`). | zero-key | | `metalworks models warm` | Pre-download the local embedding model so the first run isn't blocked on it. | zero-key | ## research Plan and run demand-research reports, then derive everything else from them. The report-grounded commands (`position`, `landscape`, `design`, `assess`, `refresh`, `versions`) take a **report id** — but it's **optional**: omit it to use your latest run, or pass a unique **prefix** instead of the full id. No more copy/pasting UUIDs between steps. (`research --help` groups these by *Core flow* / *Pillars & build* / *History*.) | Command | Description | Keys | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `metalworks research plan PROMPT` | Walk the D1-D8 planner over a prompt and write a `brief.json` (recommended option auto-selected, non-interactive). | chat key | | `metalworks research run` | Run the research pipeline from a `--question` (no brief needed) or a `--brief` file. Stores the report. | chat key | | `metalworks research list` | List stored research runs — the report ids the report-grounded commands take. | zero-key | | `metalworks research refresh REPORT_ID` | Re-run a stored report against your latest [research data](/docs/corpus) → an updated report saved as a new version, plus what changed. | chat key | | `metalworks research versions REPORT_ID` | List a report's versions, oldest → newest. | zero-key | | `metalworks research diff REPORT_A REPORT_B` | Show the diff between two stored report versions. | chat key | | `metalworks research position REPORT_ID` | Derive grounded positioning from a stored report (one LLM call). | chat key | | `metalworks research design REPORT_ID` | Author a grounded-but-directional design system (SAFE/RISK choices + `DESIGN.md`) from a stored report; a real competitor teardown when a browser is installed. | chat key | | `metalworks research logo REPORT_ID` | Generate diverse logo options (SVGs + a picker) drawn under the report's design system. | chat key | | `metalworks research design-review URL` | Deterministically audit a rendered page's computed styles vs design hard-rules (and, with `--report`, a design system). Needs the browser. | none (chat with `--report`) | The **[validation loop](/docs/validation-loop)** — frame an idea, then decide if it's worth building: | Command | Description | Keys | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `metalworks research ideate ""` | Idea-first: sharpen a raw idea into a testable hypothesis + a brief to run demand on. | chat key | | `metalworks research ideate --from-report REPORT_ID` | Evidence-first: surface a stored report's forks (candidate wedges / top clusters) as grounded idea sketches to pick from. | chat key | | `metalworks research landscape REPORT_ID` | The full "what exists today" — the competitor map **plus** an empirical existing-solutions scan (real shipped products, matched to demand clusters). | chat key | | `metalworks research assess REPORT_ID` | The **GO / PIVOT / NO-GO** verdict — a deterministic gap over demand × landscape. PIVOT names an under-served fork to aim at. | chat key | | `metalworks research validate ""` | Run the whole loop: ideate → demand → landscape → assess, looping on PIVOT until GO, NO-GO, or exhausted. **Interactive by default** — you make the call each round (the engine's recommendation is the default); pass `--auto` to run it headlessly. The final report is saved. | chat key | Options: * `research plan` — `--out, -o PATH` (default `brief.json`). * `research ideate` — `IDEA` argument (idea-first) **or** `--from-report REPORT_ID` (evidence-first; id or prefix); `--out, -o PATH`. * `research landscape` / `assess` — optional `REPORT_ID` (id or prefix; defaults to your latest run); `--out, -o PATH` to write the JSON. * `research validate` — `IDEA` argument; `--auto/--no-auto` (headless vs interactive, default interactive); `--max-iterations INT` (loop cap before `exhausted`, default 4); `--out, -o PATH`. * `research run` — `--question, -q TEXT` *or* `--brief PATH` (pass exactly one); `--subreddit TEXT` (repeatable, else auto); `--source TEXT` (repeatable — which [sources](/docs/sources) to ingest from; else configured/Reddit); `--months INT` (corpus window, default 12); `--out, -o PATH` to write the report JSON. * `research list` — `--limit INT` (max runs to show, default 20). * `research refresh` / `versions` — optional `REPORT_ID` (id or prefix, any version of the report; defaults to latest); refresh updates from the lineage head and takes `--out, -o PATH`. * `research diff` — `REPORT_A REPORT_B` arguments (earlier, later; both required). * `research position` / `landscape` — optional `REPORT_ID` (id or prefix; defaults to latest); `--out, -o PATH` to write the artifact JSON. * `research design` — `REPORT_ID` argument; `--name` brand name; `--out, -o DIR` for `DESIGN.md` + `preview.html`; `--max-teardown N` competitor sites to teardown (`0` = all). * `research logo` — `REPORT_ID` argument; `--name` brand name; `--out, -o DIR` for the SVGs + `picker.html`; `--count, -n` how many options (design angles). * `research design-review` — `URL` argument; `--report REPORT_ID` to also grade against that report's design system; `--json PATH` for the `DesignReview` JSON. ## corpus Grow and inspect your [saved research data](/docs/corpus) — what research reads from. A `research run` saves what it reads automatically, but you can also add to it directly to build up evidence over time and across sources. | Command | Description | Keys | | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------- | | `metalworks corpus add --source -q "..."` | Pull a source's items for a query into the corpus (idempotent — re-adding upserts by id). | depends on source | | `metalworks corpus sync` | Re-pull the latest window for the enabled sources. | depends on source | | `metalworks corpus stats` | Records + comments in the corpus, broken down by source. | zero-key | Options: `corpus add` — `--source TEXT` (the source id, e.g. `reddit` / `hackernews` / `web`); `-q, --query TEXT`; `--limit INT`. ## sources List and toggle the [data sources](/docs/sources) research ingests from. | Command | Description | Keys | | --------------------------------- | ----------------------------------------------------------- | -------- | | `metalworks sources list` | Registered sources + whether each is enabled and reachable. | zero-key | | `metalworks sources enable ` | Enable a source (writes the `[sources]` config table). | zero-key | | `metalworks sources disable ` | Disable a source. | zero-key | ## build Scaffold an evidence-grounded build harness from a report (see the [Build spec](/docs/build-spec)). | Command | Description | Keys | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `metalworks build init [REPORT]` | Turn a stored report into a build plan and scaffold a project for your coding agent (no product code). `REPORT` is optional — an id/prefix, a `report.json` path, or omitted for your latest run. | chat key | `REPORT` is a stored report id (from `research list`) **or** a path to a `report.json`. Options: * `--dest, -d PATH` — directory to scaffold into (default `./build`). * `--surface TEXT` — `auto` (default) lets the spec pick the surface + explain why, or pin one: `web` | `mobile` | `cli` | `api` | `sdk` | `browser_extension` | `desktop`. * `--base TEXT` — stack hint recorded in the spec, e.g. `next-shipfast` (default `empty`). ## distribution Plan where this product gets distributed, off a stored report (see [Distribution](/docs/distribution) and [GEO / LLM-citability](/docs/distribution-geo)). | Command | Description | Keys | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `metalworks distribution strategy [REPORT]` | Route the report's named entities + signals into **test→focus** channel experiments; every channel traces to a real corpus entity. | chat key | | `metalworks distribution assets [REPORT]` | Draft channel-shaped, drafting-only distribution assets per channel — each claim-bearing line carries a real permalink and exact text span. **Never posts.** | chat key | | `metalworks distribution data-report [REPORT] --kind ...` | Project a stored report into a corpus-derived data report — a deterministic ranking of its clusters with **real** counts, real permalinks, and a verbatim quote per row. `--kind`: `complaint_index` \| `feature_ranking` \| `state_of`. **No LLM.** | zero-key | | `metalworks distribution geo [REPORT]` | The GEO / LLM-citability stream — participation targets (real threads from the report's permalinks), citability probes, and answer-first answer briefs (grounded; evidence resolves, ungrounded dropped). Drafting only. | chat key | | `metalworks distribution engage [REPORT] --permalink URL --why "…"` | Distribution's **participation/execution arm** (D9) — draft a DISCLOSED, founder-voiced, compliance-gated reply for one GEO participation target (a real thread). Reuses the Reddit reply machinery + the single voice system's no-upvote / native-first / no-AI-tell invariants. Posting stays gated — a human posts via `metalworks reddit post`. Drafting only. | chat key | | `metalworks distribution requirements [REPORT]` | The distribution → build requirements (D3) — embedded-loop build requirements (loop kind → concrete things to build, grounded in the channel) + the conversion-surface destination the channels point at. Feeds the build spec. | chat key | | `metalworks distribution plan [REPORT]` | The distribution plan (D7) — the report's channels sequenced into **pushes** (spike channels at deterministic playbook timings: Product Hunt 12:01am PT Tue/Wed, Show HN Tue-Thu 8-10am, …; one all-day-attention channel per day, never PH + a big HN push the same day) + **streams** (compounding channels run continuously). Pre-launch warming → staggered push week → 30-day post step. Drafting + planning only. | chat key | | `metalworks distribution measure [REPORT]` | Close the distribution loop (D8) — the per-channel **success metric** (what "worked": launch platform → top-N + attributed signups; marketplace → installs + WAU; community → qualified replies + click-through; GEO → citation appearances) + the **instrumentation** to wire BEFORE the push (a UTM tag, an attributed-signup query, a citation check), read deterministically by surface type. Record `ChannelResult`s and feed them back to re-rank the next push. | chat key | `REPORT` is an id/prefix or omitted for your latest run. Both accept `--out, -o PATH` to write the JSON result. ## reddit Search Reddit, fetch intel, and post (gated). The `[reddit]` extra is required; search and intel need **no API key**, only posting needs OAuth credentials. | Command | Description | Keys | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | | `metalworks reddit search QUERY` | Search public Reddit submissions. | zero-key (`[reddit]`) | | `metalworks reddit subreddit info NAME` | Subreddit intel: description, subscribers, top titles, rules. | zero-key (`[reddit]`) | | `metalworks reddit subreddit rules NAME` | List a subreddit's posting rules. | zero-key (`[reddit]`) | | `metalworks reddit auth login` | Start the Reddit OAuth loopback flow and store the connected account. | Reddit OAuth | | `metalworks reddit post URL --text ...` | Reply to a thread. Runs the deterministic compliance gate **first**; refuses on fail. Dry-run by default. | Reddit OAuth | Options: * `reddit search` — `--subreddit TEXT` (restrict to r/X); `--limit INT` (default 15). * `reddit auth login` — requires `REDDIT_CLIENT_ID` / `REDDIT_CLIENT_SECRET` in the env; you paste the `code` from the redirect URL. * `reddit post` — `URL` argument; `--text TEXT` (the reply, required); `--username TEXT` (which connected account); `--yes` (actually send — default is a dry-run that prints the verdict and stops). ## discovery Find and draft Reddit reply opportunities (drafts only; never posts). | Command | Description | Keys | | -------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------- | | `metalworks discovery run --query ...` | Search Reddit, draft replies, and gate each through the compliance check. **Produces drafts only.** | chat key (`[reddit]`) | Post a chosen draft yourself with `metalworks reddit post --text ...`. ## arctic Read the Arctic Shift historical corpus. **Zero-key** — needs the `[arctic]` extra (duckdb). | Command | Description | Keys | | ---------------------------------- | ------------------------------------------------------------------ | --------------------- | | `metalworks arctic months` | Print the latest available submissions month in the Arctic corpus. | zero-key (`[arctic]`) | | `metalworks arctic pull SUBREDDIT` | Pull submissions for a subreddit from the corpus → table or JSONL. | zero-key (`[arctic]`) | Options for `arctic pull`: `--months INT` (how many months back, default 1); `--out, -o PATH` (write rows as JSONL; otherwise prints a table preview). ## config Read and write non-secret config (cwd over the user config dir). **Zero-key.** Secret keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, provider/search/Reddit keys, `METALWORKS_FERNET_KEY`, `METALWORKS_MCP_TOKEN`) are refused — they must come from the environment. | Command | Description | | --------------------------------- | ---------------------------------------------------------------- | | `metalworks config list` | Print the merged non-secret config. | | `metalworks config get KEY` | Print one config value (file only). | | `metalworks config set KEY VALUE` | Set one non-secret value in the cwd config. Refuses secret keys. | ## mcp Run the metalworks MCP server (see the [MCP tools reference](/docs/mcp-tools)). | Command | Description | | ---------------------- | ---------------------- | | `metalworks mcp serve` | Launch the MCP server. | Options: `--transport TEXT` (`stdio` default — keyless; or `sse`); `--port INT` (SSE port); `--host TEXT` (SSE bind host); `--token TEXT` (bearer token). The `sse` transport is network-exposed and **refuses to start without a bearer token** (`--token` or `METALWORKS_MCP_TOKEN`); `stdio` is the keyless default.