@cardstack/deck-cli is not on npm, and there is no plan to put it there until this
has been thoroughly tested.
Do not run npx deck. There is a package called deck on the public
registry, at version 0.0.4, and it is not this one — it belongs to somebody
else. npx deck hello would download and run a stranger's code. Install
from this repository instead.
| Node | ≥ 22 | required — the CLI is TypeScript with no build step, and relies on Node's native type stripping |
| pnpm | 11 | required to install the workspace's dev dependencies (packageManager pins the exact version) |
| jj | any recent | optional — History via the jj CLI when no daemon is running |
| Rust / cargo | stable | optional — only to build packages/deckd, the in-tree History daemon |
Verified on Node v24.17.0, pnpm 11.0.9, jj 0.43.0.
Without jj or deckd everything still works and nothing is lost: the store
keeps every settled save as an immutable -dev.N version. What you give up
is the states between publishes. The CLI says which backend it attached,
every time, rather than pretending.
git clone git@github.com:christse/deck.gitcd deck && pnpm installThere is no build step. pnpm install fetches dev dependencies and links
the five workspace packages together; the CLI runs the .ts sources
directly.
1 — Straight from the repo. Nothing to install, nothing on your PATH:
node packages/cli/bin/deck.js hello ./playground2 — A symlink on your PATH. bin/deck.js carries a shebang and is
executable, and Node resolves a symlink to the real file before it resolves
imports — so the workspace's dependencies still resolve through it:
ln -s "$PWD/packages/cli/bin/deck.js" ~/.local/bin/deck3 — pnpm's global link, if you would rather pnpm own the linkage:
pnpm --filter @cardstack/deck-cli link --globalUndo either with rm ~/.local/bin/deck or
pnpm --filter @cardstack/deck-cli unlink --global.
Whichever you pick, the rest of the docs write deck; substitute
node packages/cli/bin/deck.js if you chose the first.
Three checks, in increasing strength.
It runs, and knows what it can do:
deck helpIt obeys its own contract. This stands the canonical fixture depot up on the reference server and measures it against all twelve laws:
deck conformExpect 49 passed, 0 failed, 3 not applicable — the three are at-rest laws
that the HTTP half does not cover, and they are checked by the other half of
the same run.
The whole workspace is sound:
pnpm test && pnpm lintExpect 189 core, 22 history, 79 server, 4 conformance, 13 CLI — all passing — and no lint or type errors.
deck hello ./playgroundThe banner it prints includes a line naming the history backend it attached to, or the reason it could not. An attached deckd means every-save History and a Step per save; anything else means Versions only, which still keeps every settled save as an immutable version.
| Variable | Default | What it does |
|---|---|---|
DECK_KEYRING |
~/.deck/keys |
where deck keygen writes private keys. They never leave the machine |
JJ_BIN |
jj |
which jj binary to seal with when no daemon URL is set |
DECKD_URL |
— | point the History at in-tree deckd (packages/deckd, default listen http://127.0.0.1:8787). Preferred over DECK_HISTORYD_URL when both are set |
DECK_HISTORYD_URL |
— | legacy alias for an external historyd; same HTTP contract as deckd |
To run Hub with deckd from this clone:
./scripts/run-hub-with-deckd.shThat builds packages/deckd if needed, starts it on :8787, and starts Hub
on :8788 with DECKD_URL set. See packages/deckd/README.md
and docs/deck-daemon.md.
| What you see | What it means |
|---|---|
Unknown file extension ".ts" |
Node is older than 22 |
Cannot find package '@cardstack/deck' |
pnpm install has not run, or you are running a copy of packages/cli from outside the workspace |
EADDRINUSE from deck serve |
the port is taken. deck hello walks forward up to ten ports on its own; serve does not, because a server you asked to be on 8788 should not quietly be somewhere else |
deck: --realm is now --depot |
an old flag. It still works and will keep working; the message is a note, not a failure |
| history reports Versions only | deckd is not running (DECKD_URL / DECK_HISTORYD_URL point at nothing). The live loop is unaffected |
Remove the symlink or global link, then delete the clone. A depot is
self-contained — its store and its seals live inside the depot directory —
so nothing the CLI made is left behind anywhere else, except any keys under
~/.deck/keys.