Repository navigation
CLI Importing
Imports copy an entry, and whatever it requires, from the stack into a project. The project records what it took and from which commit, in stack.toml. Later commands compare the project against that record. Nothing is linked or loaded globally: a project has only what it imported.
Each import is recorded in the project's stack.toml, and the managed blocks in .gitignore and AGENTS.md are refreshed (see below).
Where things land:
| Entry | Lands in the project at | In git |
|---|---|---|
| skill, style |
.agents/skills/<name> plus relative symlink .claude/skills/<name>
|
ignored, restored by stack sync
|
entry with a payload folder (templates) |
the payload's contents, at the project root; the entry README stays in the stack | committed |
| anything else (systems, workers, libraries, assets, ...) |
.stack/<id>, e.g. .stack/systems/engineering-conventions, .stack/workers/mel
|
ignored reference copy, restored by stack sync
|
Anything imported --to a project path (a component into src/, a logo into public/) is committed, as is stack.toml itself.
stack init [--project <dir>]
stack init --components [lib...] [--dry-run] # track remote libraries; see Remote LibrariesCreates stack.toml and the managed blocks in .gitignore and AGENTS.md. You do not have to run it first: import creates stack.toml when it is missing, and so does preset apply. Run init when you want the files in place before the first import. stack import creates stack.toml and both managed blocks implicitly, so run explicit stack init only to migrate a legacy stack.lock.json — for a fresh project, just import.
$ stack init --project ./my-app
created stack.toml
ignore updated .gitignore (managed escacs block)
agents updated AGENTS.md (managed escacs block)
Running it again when nothing is imported is safe:
$ stack init --project ./my-app
stack.toml already initialized
When the project already tracks imports, init refuses and changes nothing:
$ stack init --project ./upd
stack.toml already tracks 2 imports; nothing to do
A legacy stack.lock.json is migrated to stack.toml by the first command that writes the record (init, import, update or remove). The JSON file is then deleted.
stack import <id...> [--to <dir>] [--ref <rev>] [--dry-run] [--project <dir>]Copies each entry and everything it requires from the stack's HEAD, or from --ref, into the project, then records it in stack.toml. A library id (components/<library>) imports every member component.
| Flag | Effect |
|---|---|
--dry-run |
print the plan (what lands where, the gitignore and AGENTS.md changes) and write nothing |
--to <dir> |
put one entry somewhere else, for example --to src/components/button. Accepts one id at a time |
--ref <rev> |
use another stack commit, tag or branch instead of HEAD
|
--ref pins the import to that commit. A rev the stack does not have fails:
stack ref "nosuchref" not found in /path/to/stack
What lands where:
| What | Lands in | Ignored by git |
|---|---|---|
| skill, style |
.agents/skills/<name>/, plus a relative link .claude/skills/<name>
|
yes (both paths) |
template (has a payload) |
the project root, laid out like the template | no: project-owned |
| component, library, other kinds |
.stack/<id>/, for example .stack/libraries/tailwindcss/, .stack/workers/mel/, .stack/components/base/button/
|
yes |
any entry with --to (or a preset row with to) |
the given project path | no: project-owned |
Two details: an entry imported with --to does not get the .claude/skills link unless it lands at .agents/skills/<name>; and required entries always go to their default place, not to --to.
The dry run shows the same plan, prefixed by would:
$ stack import components/base/button --dry-run --project ./my-app
import components/base/button -> .stack/components/base/button
ignore would update .gitignore (managed escacs block)
agents would update AGENTS.md (managed escacs block)
dry run: nothing written
Refusals. An import stops before it writes anything in these cases:
-
An entry is not committed to the stack yet:
skills/zz-uncommitted is not an entry at stack commit <sha> (new entries must be committed to the stack before importing) -
A file the import would write already exists in the project with different content. The import lists every such file and asks you to move them or pick
--to:these files already exist with other content; move them or choose --to: .agents/skills/file-pr/SKILL.mdA
--dry-runof the same import does not fail. It prints the conflict and exits 0:CONFLICT .agents/skills/file-pr/SKILL.md (exists with other content; a real import would abort) -
--towith more than one id:--to works with one id at a time.
Importing an entry that is already imported does not re-copy it. It prints have ... (use stack update for newer versions) and moves on.
stack status [--ref <rev>] [--project <dir>]Shows each import, and whether it is edited locally or has updates in the stack. The commit shown in the header is the stack's HEAD (or --ref).
The human layout prints one state per import:
| State | Meaning |
|---|---|
imported |
matches what was recorded, and the stack has not changed it |
edited |
at least one file differs from the recorded copy |
update |
the stack has a newer version of at least one file |
gone |
the entry was removed from the stack |
When more than one applies, the first of gone, update, edited wins as the state. The detail column still lists the others. The summary line counts them:
stack at 43f3bdb
edited skills/file-pr @43f3bdb .agents/skills/file-pr edited here: SKILL.…
imported skills/leaving-pr-comments @43f3bdb .agents/skills/leaving-pr-comments
2 imports · 1 edited
Once the stack has moved on, the summary says 1 update · next: stack update. A removed entry adds · 1 gone.
The plain layout marks rows that need attention with *:
stack at bb28b84
* skills/file-pr @010d50a -> .agents/skills/file-pr (update: 1 file; edited here: SKILL.md)
skills/leaving-pr-comments @010d50a -> .agents/skills/leaving-pr-comments
Plain detail text is removed from stack, update: N file(s) and edited here: <files>.
--json gives { command, commit, rows }, where each row has id, path, commit, local (edited files), upstream (files that changed in the stack) and gone.
stack update [id...] [--ref <rev>] [--dry-run] [--project <dir>]Moves imports to the stack's HEAD, or to --ref. Local edits are merged with a three-way merge (git merge-file), using the recorded copy as the base. With no ids, every import moves. Entries already at that commit are skipped.
$ stack update
merged .agents/skills/file-pr/SKILL.md (kept your edits)
update skills/file-pr -> 9fc1eca (1 file changed upstream)
update skills/leaving-pr-comments -> 9fc1eca (0 files changed upstream)
The lines that can appear:
| Line | Meaning |
|---|---|
update <id> -> <commit> (N files changed upstream) |
the entry moved |
merged <path> (kept your edits) |
local and upstream changes merged cleanly |
CONFLICT <path> (N conflicts; resolve the <<<<<<< markers) |
the merge left markers in the file |
kept <path> (removed in the stack, edited here) |
the stack deleted the file, but it was edited here |
skip <path> (deleted here; the stack changed it) |
the file was deleted here and the stack changed it; not restored |
gone <id> was removed from the stack; kept as is |
the entry no longer exists upstream; stack remove drops it |
up to date with <commit> |
nothing moved |
Two things to know about conflicts:
- A conflict does not stop the update. The file gets the markers, and the entry's commit still moves to the new
HEAD.updateexits 0. - A second
updatedoes not report that conflict again. In a run where the conflict was left in place, the nextupdate --jsonreturnedupToDate: truewithconflicts: []. Checkstack status(the file shows asedited) and resolve the markers before you commit.
--dry-run predicts the same lines and writes nothing. update does not touch .gitignore; it refreshes the AGENTS.md block only when the record moved.
stack remove <id> [--dry-run] [--project <dir>]Deletes an import's files that are still unedited, the .claude/skills link if it has one, and its entry in stack.toml. A file edited here is kept, and so is the folder it sits in:
$ stack remove skills/file-pr --project ./my-app
kept .agents/skills/file-pr/SKILL.md (edited here)
ignore updated .gitignore (managed escacs block)
agents updated AGENTS.md (managed escacs block)
remove skills/file-pr
If other imports require the entry you remove, remove says so, and it still removes the entry:
note skills/file-pr require skills/leaving-pr-comments
--dry-run lists the files it would delete (delete <path> (would remove)) and writes nothing.
stack sync [--dry-run] [--project <dir>]Restores ignored imports from stack.toml, each at its recorded commit: the step a fresh clone of a project needs. It restores missing files and skips the ones already in place. It never overwrites a file that was edited here.
$ stack sync --project ./rapp
restored .stack/libraries/tailwindcss/README.md
sync done: 1 file restored, 0 kept (edited here)
Running it again restores nothing and prints sync done: everything already in place. A recorded commit that is not in the stack clone fails the command with a fetch hint (... is not in this clone (fetch first), from the code). Sync needs the stack checkout that holds those commits, so run that checkout's stack with --project.
Two blocks are rewritten by the CLI and should not be edited by hand.
.gitignore: between # >>> escacs stack and # <<< escacs stack. It lists only the agent material that sync can restore: .agents/skills/<name>/, the .claude/skills/<name> links and .stack/. Template payloads and --to paths are project-owned and never listed. init, import and remove refresh it. gitignore rewrites it on demand:
$ stack gitignore --project ./life
.gitignore already up to date (2 ignored)
# >>> escacs stack
# Managed by `stack gitignore`. Do not edit between these markers.
/.agents/skills/leaving-pr-comments/
/.claude/skills/leaving-pr-comments
# <<< escacs stackThe block lists the ignored paths of the imports that are in stack.toml. In this example only leaving-pr-comments was left, after file-pr was removed.
AGENTS.md: a ## Escacs stack section between <!-- >>> escacs stack --> and <!-- <<< escacs stack -->. It lists each import as id -> path and gives a short command cheat sheet. Text outside the markers is left alone. Init, import, update, remove and sync refresh it. If the project still has the old hand-pasted snippet from templates/agents-md, delete it; the next stack command writes the managed block.
stack.toml is the record. Commit it, and treat it as generated: the commands write it, and the reader fails loudly on any shape it does not know. A project that imported skills/file-pr looks like this (abridged: the record for skills/leaving-pr-comments is omitted):
# Escacs stack imports. Managed by `stack import/status/update/remove`; commit this file.
stack = "https://github.com/escacs/stack"
[entries."skills/file-pr"]
commit = "43f3bdbcaea8728fabea086d9a50eb539c261098"
path = ".agents/skills/file-pr"
links = [".claude/skills/file-pr"]
requires = ["skills/leaving-pr-comments"]
[entries."skills/file-pr".files]
"LICENSE" = "eccbd9f1c676d8cbb191a5064c48118492b74125"
"SKILL.md" = "c2dea189cec7e24131b7afea412fe445230c107a"Each entry records the stack commit, the project path, any links and requires, the entry that required it (requiredBy), and a git blob id for every file. The blob ids are how status tells edited files from unedited ones. Remote libraries add a [remotes."<lib>"] table with url, ref, path and the commit that was synced (see CLI Remote Libraries).
Why stack.toml replaced the JSON lock: https://github.com/escacs/stack/blob/main/docs/decisions/0002-opt-in-imports.md (private repo).
See also: CLI Presets, CLI Recipes, CLI Remote Libraries.
Stack desktop client + CLI wiki — condensed from the repo docs. App repo: https://github.com/escacs/stack-app. CLI repo (private): https://github.com/escacs/stack.