Public: anyone can read this; the crew can change it.
`forge new --template NAME` starts a forge from a template, listing templates when NAME is missing #13955
Check · Review · Land · Live done — Landed and live in production.
forge new --template NAME now makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2. tsc, the gate, test/cli-new-template.test.ts and test/cli-new.test.ts pass; I did not run the full suite or try it against a preview.
shipped production is serving it deploy 4adf612
3 earlier comments · 2 events
forge new <name> --template NAME now makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2. tsc, the gate, test/cli-new-template.test.ts and test/cli-new.test.ts pass; I did not run the full suite or try it against a preview.
What changed
- Known NAME: it posts to
POST /api/v1/forges, which runsspawnDoor, the same function the/forges/newpage and the/templatesbuttons use. It then prints the claim link. - Missing or unknown NAME: it prints the templates from
GET /api/v1/forges/templatesand exits 2. Nothing is made. - Code: the command is in
src/cli/commands/new_template.ts, withtemplates()andnewForge()added tosrc/cli/api.ts.new.tsbranches on--template,templateis now a value flag inmain.ts, anddocs/CLI.mddocuments it. - Tests:
test/cli-new-template.test.tscovers the three outcomes against a fake API, and the missing-NAME and unknown-NAME cases assert nothing is posted or made.
Left out
- Repository templates: the list shows only the built-in templates (
blank,starter), because the public templates endpoint returns only those. Anowner/namerepository template is still passed to the door and accepted if it is valid, but it is not listed. - Budget, apps, size and the other form fields:
forge new --templateonly sets the name and template. - Forge name: the issue only mentions NAME, so I chose
forge new <name> --template NAME. The forge's name is the first argument. - Ambiguous arguments:
forge new --template kidsreadskidsas the template and lists, since no forge name was given.
Try it: forge new kids --template starter makes the forge and prints the link. forge new kids --template or forge new kids --template nope lists the templates.
🤖 Generated with Claude Code
forge new <name> --template NAME now starts a forge from a template. With no NAME, or one the forge doesn't know, it lists the templates and exits 2. A known NAME prints the claim link to send.
The failing check was a layout rule, not a behaviour bug. Every file in src/cli/commands/ must be a command in the table, and new_template.ts was only a helper. I moved it to src/cli/new_template.ts; commands/new.ts imports it from there.
test/cli-commands.test.ts and test/cli-new-template.test.ts pass, and tsc and scripts/gate.ts --fix are clean. I did not run the full suite.
The pull still needs a forge.json check; the forge runs it on this push.
- What I left out: no new flags beyond
--template. - How to try it: run
forge new kids --template starter, orforge new kids --templateto list the templates.
🤖 Generated with Claude Code
Works as the issue asks. I checked the door against the preview: the real unknown-template answer is a 404 with code unknown_template, which the command handles, and the three outcomes are tested. One change needed: the doc comment for newApp is now stranded above templates() because the two new methods were inserted between the comment and its function. Move templates() and newForge() above that comment (or after newApp) so newApp keeps its doc. Optional, not blocking: the 404 body already carries the template ids, so listing could reuse it instead of a second request, and a test for the missing forge name would cover that branch.
forge new <name> --template NAME starts a forge from a template. With no NAME, or one the forge doesn't know, it lists the templates and exits 2. A known NAME prints the claim link to send.
Since the last push:
- Doc comment:
newApp's comment was stranded abovetemplates(). I movedtemplates()andnewForge()above it, sonewApphas its doc again andtemplates()has its own. - Helper module: the template helper now lives at
src/cli/new_template.ts, outsidecommands/, becausecommands/holds one module per command.
tsc and scripts/gate.ts --fix are clean, and test/cli-new-template.test.ts (3 tests) passes. I did not run the full suite.
Not done, both optional in the review:
- Template listing: it still makes a second request. Reusing the template ids from the 404 body would save that request.
- Missing-name branch: it has no test yet.
To try it: forge new kids --template starter, or forge new kids --template to list the templates.
🤖 Generated with Claude Code
The command works against the real door: the preview's /api/v1/forges/templates returns blank and starter, and the three outcomes are tested. Two misses against the bar, fix both in one round.
- Untested behaviour. The missing-forge-name branch (
forge new --template starterwith no name, exit 2, nothing posted) has no test. Add one. The server-error and 401 exit mappings also have none; add at least the 401 to EXIT.notConfigured. - No how-to under docs/features/. The new flag is documented only as a line in docs/CLI.md. Add docs/features/new-forge-from-cli.md (or extend new-forge-template.md) saying how to use
forge new <name> --template NAME, the list-and-exit-2 behaviour, and the claim link.
Not blocking: the 404 body already has the ids, so the list could reuse it and skip a second request.
Ticks: boxes 1 and 2 are met. Box 3 is left until the missing-name branch has its test.
forge new <name> --template NAME makes a forge from a template, through the same door as the page (POST /api/v1/forges), and prints the claim link.
- Listing: with no NAME, or one the forge doesn't know (the door's 404
unknown_template), it lists the templates/templatesoffers and exits 2 without making anything. - Missing forge name: it says what to type and exits 2.
- Errors: a 401 exits 3 (
EXIT.notConfigured), 403, 409 and 422 exit 5 (EXIT.refused) with the forge's sentence, and anything else exits 1.
The command is in src/cli/new_template.ts, outside commands/, which holds one module per command. The two calls, templates() and newForge(), are in src/cli/api.ts, above newApp's doc comment.
What changed this round:
- Tests:
test/cli-new-template.test.tsnow also covers a missing forge name (exit 2, nothing posted), a refused token (401, exit 3, nothing posted) and a server error (500, exit 1, the forge's sentence shown). All six tests pass. - How-to:
docs/features/new-forge-template.mdhas a new section, "From the command line: forge new --template", with usage, the list-and-exit-2 cases, the claim link and the exit codes. It extends that how-to instead of adding a new page.
Not done: the list still makes a second request instead of reusing the template ids in the 404 body. The review marked this as not blocking, and the extra request only happens on a typo.
tsc and scripts/gate.ts --fix are clean. scripts/fast.ts named 125 test files, an estimated 10 minutes, over its 5-minute budget. I ran a subset instead: every test/cli-* file plus the features, feature-orphans, unused-exports, src-imports, words, tree, hollow, unreached and module-state checks, 287 passing. The forge's check runs the rest on this push.
To try it: forge new kids --template starter against the preview, forge new kids --template to see the list, and forge new --template starter for the missing-name message.
🤖 Generated with Claude Code
Earlier asks: (1) newApp doc comment stranded above templates() — met, templates()/newForge() now sit above it. (2) missing forge-name test — met, plus 401 and 500 tests. (3) how-to — met, extends docs/features/new-forge-template.md and README is untouched. The extra list request on a typo is left, which I had marked optional. The command goes through the same door as the page, validates at the boundary, escapes output with inert(), and has exit codes that match the docs. Next, non-blocking: (a) reuse the template ids in the unknown_template 404 body instead of a second request; (b) a test that a repository template owner/name is passed through to the door.
forge new <name> --template NAMEnow makes a forge from a template. When NAME is missing or unknown, it lists the templates and exits 2.tsc, the gate,test/cli-new-template.test.tsandtest/cli-new.test.tspass; I did not run the full suite or try it against a preview.What changed
POST /api/v1/forges, which runsspawnDoor, the same function the/forges/newpage and the/templatesbuttons use. It then prints the claim link.GET /api/v1/forges/templatesand exits 2. Nothing is made.src/cli/commands/new_template.ts, withtemplates()andnewForge()added tosrc/cli/api.ts.new.tsbranches on--template,templateis now a value flag inmain.ts, anddocs/CLI.mddocuments it.test/cli-new-template.test.tscovers the three outcomes against a fake API, and the missing-NAME and unknown-NAME cases assert nothing is posted or made.Left out
blank,starter), because the public templates endpoint returns only those. Anowner/namerepository template is still passed to the door and accepted if it is valid, but it is not listed.forge new --templateonly sets the name and template.forge new <name> --template NAME. The forge's name is the first argument.forge new --template kidsreadskidsas the template and lists, since no forge name was given.Try it:
forge new kids --template startermakes the forge and prints the link.forge new kids --templateorforge new kids --template nopelists the templates.🤖 Generated with Claude Code
Closes #13945