Deck has two halves, and the split is not negotiable: the server is read-only, and this CLI is the only thing that writes. The server watches a directory and distributes what it finds there. Everything that creates, names, seals, or moves anything happens here — or in your editor, which is the same thing, because a save IS a write.
Installing: INSTALL.md. Everything below assumes deck is on
your PATH; substitute node packages/cli/bin/deck.js if it isn't.
The whole CLI is built around a single topology, and it is the one you actually work in:
A local Deck server owns your files, watches them, serves your app, and seals every save. Third-party libraries come from npm or unpkg, and they are vendored in — pulled down once, rewritten to stay inside your own store, and served from your own server from then on.
There is no remote Deck in this picture. Nothing your app loads at runtime comes from a host you do not control, which is L6 (hermeticity) as a working arrangement rather than an aspiration. The public registries are something you pull from, deliberately, at a moment you choose — never something your app depends on being up.
Eight groups. deck help prints this map; deck help <command> explains
any one of them in full.
| Group | Commands | |
|---|---|---|
| start | stand a depot up and serve it live | hello serve |
| seal | a directory in, a verified pack out | hash pack unpack list verify |
| publish | name sealed states in a depot's store | publish tag release prune store derive verify-derivation |
| depend | what a deck uses, and which bytes answer to it | vendor vendor-tree lock verify-links |
| propose | change someone else's deck without a branch | fork offers rebase |
| endorse | who stands behind these bytes | keygen sign verify-sig |
| recall | every state the depot has been in | history restore |
| prove | the executable contract | conform |
The groups are ordered the way the work happens, not alphabetically. Most
days you will use serve and nothing else.
deck hello ./workThat scaffolds a depot, serves it, and prints a URL. Open it, edit app.js,
reload. Then the loop that runs for the rest of the day:
deck serve --root ./work --history deckd--root is a directory of depots: every child directory becomes one,
named after itself, exactly as it is addressed. What the watcher does on
every save:
- Debounce ~500ms, so a formatter's three writes are one save.
- Hash the tree. Unchanged hash, nothing happens — no version, no seal, no noise. Touching a file is not a change.
- Auto-publish
<base>-dev.N, taggeddev. Immutable from that instant. - Seal it as a Step (when deckd is attached) —
including the saves that did not publish, so the states between versions
exist too. With
DECKD_URL, deckd’s FS watch owns seals; Hub still publishes + HMR. - Announce it on
/_live/events, and any page carrying/_live/hmr.jsreloads.
The console says so as it happens:
auto-published site/you/app@0.1.0-dev.7 (2f4c8ab19e03) sealed 91c4e0b7aa22
Meanwhile the version-less URL — /site/you/app/app.js — is your working
directory, served no-store, so the browser is physically unable to show
you a stale file. That is the same file ls shows. The layout is the
address.
You never named anything to get here, and you cannot lose a save.
Libraries come from npm or a CDN, once:
deck vendor npm:leaflet@1.9.4 --depot ./work/site --publisher lib --tag latestThe module graph is walked, every cross-module reference is rewritten to
stay inside the pack, and it is sealed into your store. From then on your
app imports from your own server. If the graph reaches a host the walker
will not follow, the command fails rather than sealing a live external
reference — --allow-external and --allow-host are the deliberate opt-
outs.
For a package with dependencies of its own, vendor-tree does the whole
graph, one deck per package, so a library two of your decks share is stored
and loaded once:
deck vendor-tree npm:zod@^3.25.0 --depot ./work/site --publisher libA version published in the last 30 days is refused by default. That is not
caution about bugs; it is the shape most supply-chain attacks arrive in.
--min-age-days moves the dial, --dry-run shows the plan and writes
nothing.
Then say what your app depends on, as a range, and pin it:
deck lock --depot ./work/site --publisher you --name appThe pins are written into the tree, so cat importmap.json is the lock
file, the lock travels inside the pack, and moving a dependency forward is
an ordinary save that auto-publishes and seals like any other.
deck release --depot ./work/site --publisher you --name app \
--version 1.0.0 --from dev --tag latestThe dev line already holds the bytes. --from says which of those states
becomes 1.0.0. Zero bytes are copied — a version is a pointer (L3), so
shipping is a metadata edit, and it is instant no matter how large the deck.
deck history ./work/site
deck restore ./work/site <changeId>The state you are leaving is sealed first, so a restore is itself undoable, and the restored state auto-publishes as the next dev version. Nothing is rewound: a restore replays forward as ordinary writes. History only grows.
Eleven of the twelve laws are things this CLI will stop you doing. When a claim cannot be verified, the command exits nonzero with a reason — never a warning a build scrolls past (L11):
- Re-publishing an existing exact version. There is no unpublish and no overwrite (L4).
- Sealing a pack whose graph still reaches the live web (L6).
deck lock --checkwhen the lock is stale, or when a pin names a file that no longer exists.deck verifyon a pack with one flipped byte.deck release --require-signaturewith no valid publish endorsement (L9).deck verify-derivationwhen re-running the recorded derivation does not reproduce the tree hash. A derivation nobody can reproduce is decoration.deck rebaseon a conflicted proposal: it reports and writes nothing, not even the part that merged. A machine never damages a contributor's work.
deck verify-links and deck lock --check are deliberately offline. A
publish that silently needs a registry to be reachable is a publish that
fails at 3am.
deck conformTwelve laws, checked. With --url it measures any implementation black-box
over HTTP, which is how the Boxel realm server will eventually show that it
implements Deck. The laws themselves are in
docs/deck-laws.md — but an implementation implements
Deck by passing the suite, not by reading the file.
packages/cli/src/
main.ts the front door: legacy flag, lookup, dispatch
command.ts what a command IS, and the eight groups
registry.ts every command, in one list
help.ts help, rendered from the command records
support.ts fail(), depotAt(), port walking, cooldown flags
commands/
start.ts hello, serve
seal.ts hash, pack, unpack, list, verify
publish.ts publish, tag, release, prune, store, derive, verify-derivation
depend.ts vendor, vendor-tree, lock, verify-links
propose.ts fork, offers, rebase
endorse.ts keygen, sign, verify-sig
recall.ts history, restore
prove.ts conform
A command carries its own usage and explanation, and every help screen is
rendered from the same records the dispatcher looks up — so a command cannot
exist without documenting itself, and the docs cannot describe a command
that isn't there. packages/cli/tests/cli-test.ts asserts exactly that.
- Deckbook — the teaching tour, including a
command-by-command walkthrough of four real workloads. Open it from a
running server at
/deckbook.html, or straight off disk. - README.md — what Deck is and why.
- docs/deck-laws.md — the contract.
pnpm demo— every example running at once, athttp://localhost:8789/.