CLI reference

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.

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 <ref>`	Set the default chat model (writes `model` to the cwd `metalworks.toml`).	zero-key
`metalworks models set-fast <ref>`	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 → 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 — frame an idea, then decide if it’s worth building:

Command	Description	Keys
`metalworks research ideate "<idea>"`	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 "<idea>"`	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 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 — 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 <id> -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 research ingests from.

Command	Description	Keys
`metalworks sources list`	Registered sources + whether each is enabled and reachable.	zero-key
`metalworks sources enable <id>`	Enable a source (writes the `[sources]` config table).	zero-key
`metalworks sources disable <id>`	Disable a source.	zero-key

build

Scaffold an evidence-grounded build harness from a report (see the 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 and GEO / LLM-citability).

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.

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 <url> --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).

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.

Python

Extending

Top-level commands

models

research

corpus

sources

build

distribution

reddit

discovery

arctic

config

mcp

​Top-level commands

​models

​research

​corpus

​sources

​build

​distribution

​reddit

​discovery

​arctic

​config

​mcp

Top-level commands

models

research

corpus

sources

build

distribution

reddit

discovery

arctic

config

mcp