Skip to content

CLI Recipes

Mel edited this page Nov 10, 2026 · 1 revision

Set up a new project from a preset

mkdir my-app && cd my-app && git init
stack preset apply react-app --dry-run   # read the plan first
stack preset apply react-app
git add stack.toml .gitignore AGENTS.md
git commit -m "Import the react-app preset"

preset apply writes stack.toml, the managed blocks and the imports. The ignored agent material stays out of git through .gitignore. Commit the project-owned files: stack.toml, AGENTS.md, .gitignore, and any template payload or --to file the preset wrote (git status shows them).

Check what changed upstream, and update

stack status                # * marks rows with updates or edits
stack update --dry-run      # what would move, and any conflicts
stack update

If update reports a CONFLICT, open the file, resolve the <<<<<<< project / ======= / >>>>>>> stack markers, then:

stack status                # the resolved file shows as edited; that is expected
git add -A && git commit -m "Update stack imports"

update moves the record even when it leaves markers behind, so do not expect a second update to report the same conflict.

Recover a fresh clone

A clone of the project has stack.toml and the managed blocks, but not the ignored agent files. Restore them from the stack checkout that holds the recorded commits:

git clone <your-project-url> app
cd app
/path/to/stack/bin/stack sync --dry-run --project .
/path/to/stack/bin/stack sync --project .

sync never overwrites a file you have edited, and running it twice restores nothing the second time.

Script it

Use --json when you need fields. The one-liner below prints the id of each skill; it needs only Node:

stack list skill --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{console.log(JSON.parse(s).entries.map(e=>e.id).join("\n"))})'

Use --plain when you want lines. sed takes the id from each line:

stack list skill --plain | sed 's/^- //; s/ .*//'

Exit codes do not show every problem. A dry run or an update that reports a conflict still exits 0. Check the conflicts array explicitly. This one-liner exits 2 when there is one; the code 2 is chosen by the script, not by the CLI:

stack update --dry-run --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const o=JSON.parse(s);if(o.conflicts.length){console.error("conflicts:",o.conflicts.join(", "));process.exit(2)}})'

For a project, stack status --json returns each import's local (edited files) and upstream (files the stack changed). Those are the two lists to act on.

See also: CLI Importing, CLI Presets, CLI Output Modes.

Clone this wiki locally