CLI Reference
Every command registered by the STAK CLI (stak). All mutating commands follow: intent → plan → preview → approval → apply → result. Mutations require confirmation; pass --yes for non-interactive use — it never bypasses conflicts, integrity failures, or privacy blocks. --json (where noted) prints exactly one JSON document to stdout and nothing else; it never contains tokens, secrets, or signed URLs.
Authentication
loginSign in to STAK Cloud.
stak login [--api-url <url>] [--label <label>] [--no-browser]Options:
- --api-url <url> — override the Cloud API base URL
- --label <label> — a human-readable label for this device/session
- --no-browser — print the device-authorization URL instead of opening a browser
Examples:
stak login
stak login --label "work laptop"Notes:
- Browser device-authorization flow; stores an opaque token under $STAK_HOME/auth.json.
logoutSign out of STAK Cloud on this machine.
stak logoutExamples:
stak logoutNotes:
- Revokes the server token where reachable and removes the local credential.
whoamiShow the signed-in account.
stak whoami [--json]Options:
- --json — print exactly one JSON document to stdout
Examples:
stak whoami
stak whoami --jsonNotes:
- Never prints the token.
Environment
initCapture the current global Skills as the desired Environment `main`.
stak initExamples:
stak initstatusShow machine vs. `main` vs. STAK Cloud: untracked/modified/missing Skills and sync state.
stak status [--json] [--verbose]Options:
- --json — print exactly one JSON document to stdout
- --verbose — show detailed internal state
Examples:
stak status
stak status --jsonNotes:
- Reports satisfied, modified, missing, not installed, uncertain, untracked, and drift states.
- Missing: the Skill was on this machine and is gone (`stak remove` drops it from `main` if deliberate). Not installed: in `main` but never set up here, normal right after `stak pull`; run `stak run <agent>`.
addStage untracked or modified Skills (and, with `.`, Memory/Projects) into `main`, like `git add`.
stak add <selector...>Examples:
stak add some-skill
stak add .Notes:
- `stak add .` also stages all eligible current Memory (and, via the same local registry sync, portable Project state) into the local Memory manifest — never contacting Cloud.
- Staging is local only; nothing reaches STAK Cloud until `stak push`.
diffCompare this machine to `main`.
stak diff [--json]Options:
- --json — print exactly one JSON document to stdout
Examples:
stak diff
stak diff --jsonNotes:
- Reports satisfied, modified, missing, not installed, uncertain, untracked, and drift states.
scanRead-only discovery of Skills across agent roots.
stak scan [--project] [--json]Options:
- --project — scan this project directory in addition to global agent roots
- --json — print exactly one JSON document to stdout
Examples:
stak scan
stak scan --project --jsonNotes:
- Never mutates anything.
openOpen the STAK web app's Overview with this machine selected.
stak open [--print]Options:
- --print — print the URL instead of launching a browser
Examples:
stak open
stak open --printNotes:
- URL is `…/overview?machine=<machineId>` — the machine id is the only thing in the URL; no token, secret, or Memory is ever included.
- Makes no network call of its own (web sign-in is handled by the browser) and mutates nothing.
STAKs
useAdd a STAK layer to `main`.
stak use <stak> [--dry-run] [--json] [--yes]Options:
- --dry-run — preview the change without applying it
- --json — print exactly one JSON document to stdout
- --yes — skip the confirmation prompt (non-interactive use)
Examples:
stak use @owner/name
stak use ./local-stak --dry-runNotes:
- <stak> may be a local path or a public @owner/name.
- Desired-state only — no agent directories are changed.
- Remote use reacquires exact references, verifies hashes, and persists the imported version locally so subsequent status/diff/remove work offline.
- `use` does not launch an agent.
removeRemove a STAK layer from `main`.
stak remove <name|id> [--yes]Options:
- --yes — skip the confirmation prompt (non-interactive use)
Examples:
stak remove @owner/name
stak remove some-local-stak --yesNotes:
- Skills still required by other layers are preserved.
runReconcile `main` into an agent's Skill directory, then launch that agent's CLI with the Skills projected.
stak run <codex|cursor|claude> [--dry-run] [--json] [--yes] [--no-memory]Options:
- --dry-run — reconcile and preview without launching
- --json — add structured output
- --yes — skip the confirmation prompt (non-interactive use)
- --no-memory — don't share project Memory with Codex or Cursor
Examples:
stak run claude
stak run codex --dry-runNotes:
- Verifies the agent is installed first; protects unmanaged content; removes only healthy STAK-owned bindings.
- `stak run codex` launches the Codex CLI (`codex` on your PATH), not the ChatGPT desktop app.
- The launcher is shim-safe: on Windows an npm `.cmd`/`.bat` shim is executed without a shell and with argument-array semantics preserved.
- `stak run codex` and `stak run cursor` also turn on project Memory sharing for that agent and write its files before launching (see `stak memory agents`). `--dry-run` writes nothing.
tryRun a STAK in an isolated agent environment.
stak try <stak> [options] -- <agent>Options:
- --dry-run — prepare and preview without launching
- --json — print exactly one JSON document to stdout
Examples:
stak try @owner/name -- codex
stak try @owner/name --dry-run -- claude
stak try @owner/name -- cursorNotes:
- Supported agents: codex, claude, cursor.
- Runs in a temporary HOME plus a temporary agent config/state directory (CODEX_HOME, CLAUDE_CONFIG_DIR, or CURSOR_CONFIG_DIR).
- <stak> may be local or public.
- `main` and normal bindings are untouched — temporary runtime, cleanup after the session.
- Cursor trials require authentication: a normal `agent login` session is detected and reused automatically, or set CURSOR_API_KEY or CURSOR_AUTH_TOKEN.
skillManage the Skill lifecycle on this machine.
stak skill update [skill] [--json] | stak skill pause <skill> [--json] | stak skill resume <skill> [--json] | stak skill check [skill] [--json]Examples:
stak skill update
stak skill pause some-skill
stak skill resume some-skill
stak skill checkNotes:
- `update` installs approved Skill versions on this machine (no selector reconciles every Skill across every detected agent — Codex, Claude Code, Cursor; a selector narrows to that Skill).
- `pause`/`resume` change only machine-local desired state — the projection effect is realized on the next `run` or `skill update`.
- `check` only contacts each checkable Skill’s source remote and reports the result to Cloud; requires `stak login`. Never approves, installs, pauses, or resumes anything.
Projects
projectReview logical projects (derived from recovered Memory) and map recovered Memory to a directory on this machine.
stak project [list] [--json] | stak project map <project> <directory> [--json] [-y|--yes] | stak project name <project> <name> [--json] | stak project archive <project> [--json] [-y|--yes] | stak project unarchive <project> [--json]Examples:
stak project
stak project map my-app ~/code/my-app
stak project archive my-app --yesNotes:
- `list` is the default subcommand, so `stak project` on its own is equivalent to `stak project list`.
- `map` is a local binding only; the path is never shared as project identity. Refused when the directory belongs to a different repository (git-conflict) or already belongs to another logical project (identity-conflict).
- `name` sets presentation metadata only — never the Project ID, mapping, or restore behavior. Refused for Git-identified projects, and for empty, too-long (200 characters max), or path-like names.
- `archive`/`unarchive` are reversible and mirror the lifecycle change to STAK Cloud when signed in; if offline or unreachable, the failure is reported so you can re-run once connected.
- Lifecycle (active/archived) is independent of whether a project is currently available on this machine.
Memory
memoryPrivate, local, durable agent context — separate from shareable Skills and never publishable.
stak memory scan [--json] [--verbose] | stak memory backup [--json] | stak memory status [--json] [--verbose] | stak memory recover [--backup <n>] [--passkey] [--recovery-file <path>] [--json] | stak memory restore [--dry-run] [--json] [--verbose] | stak memory protect [--passkey] [--recovery-file <path>] [--json] | stak memory history [--json] | stak memory agents [--json] | stak memory agents enable|disable|reset <codex|cursor>Examples:
stak memory scan
stak memory backup
stak memory status
stak memory agents enable cursorNotes:
- `scan` is read-only discovery of portable Claude memory on this machine; changes nothing.
- `backup` copies allowlisted memory into STAK’s private store (read-only capture; native Claude files are never modified) and, when signed in, also uploads it to STAK Cloud. Commits the manifest last.
- `status` shows the last memory backup.
- `recover` downloads the private memory store from STAK Cloud onto this machine (requires sign-in). Use `recover` for explicit or history-based recovery, or when Memory is Protected; a fresh machine normally gets its Memory from `stak pull` instead.
- `restore` writes private memory into native agent Memory files. Local only — never talks to Cloud. Only writes absent targets; a differing existing target is reported as a conflict and left untouched (never merged).
- `protect` enables client-side encrypted (Protected) Cloud backup, optionally with a passkey or recovery file.
- `history` shows your Memory backup history (newest first).
- `agents` shares project Memory (notes and private instructions) with Codex (`AGENTS.override.md`) and Cursor (`.cursor/rules/stak-memory.mdc`): one-way, and kept out of Git with the repository's local exclude list. `enable` turns an agent on and writes its files, `disable` removes the files STAK wrote (a hand-edited one is kept, still excluded from Git), `reset` rewrites hand-edited STAK files, and no argument lists each agent and its status. The files are refreshed after `stak add .`, `stak pull`, `stak push`, `stak memory backup`, the final `stak memory resolve`, `stak memory materialize`, `stak memory recover`, `stak run codex|cursor` and `stak memory agents enable|reset`.
- When STAK writes Claude's private `CLAUDE.local.md` into a Git repository, it keeps it out of Git the same way: it is added to the local exclude list first (unless the repository already ignores or tracks it), and it is not written, with a note, if a `.gitignore` rule re-includes it or Git is not usable.
- Memory is captured from Claude Code; Codex and Cursor receive it through `stak memory agents`.
Cloud & Publishing
pushPush main (Skills + staged Memory) to STAK Cloud, creating a new version automatically.
stak push [--dry-run] [--json] [--yes] [--verbose]Options:
- --dry-run — preview the push without uploading or committing
- --json — emit structured JSON for dry-run
- --yes — create the cloud version non-interactively
- --verbose — show detailed cloud internals
Examples:
stak push
stak push --dry-runNotes:
- Synchronizes STAGED Skills and Memory only — nothing unstaged moves silently; run `stak add .` first to stage Memory.
- Optimistic conflict protection; no-op when unchanged. Does not change agent bindings.
pullPull the latest main (Skills + Memory) from STAK Cloud — the normal new-machine recovery path.
stak pull [--dry-run] [--json] [--yes] [--verbose]Options:
- --dry-run — preview the pull without downloading or mutating main
- --json — emit structured JSON for dry-run
- --yes — restore local main non-interactively
- --verbose — show detailed cloud internals
Examples:
stak pull
stak pull --yesNotes:
- Restores `main`, Skills, and the latest staged private Memory generation. Reference reacquisition plus a private snapshot download, all verified, then an atomic commit. Does not change agent bindings. Memory is restored on a machine with no local Memory yet; if local Memory already exists here, use `stak memory recover` instead.
publishPublish a public STAK as @owner/name from a local source or an active local layer.
stak publish <stak> [--slug <slug>] [--dry-run] [--json] [--yes]Options:
- --slug <slug> — choose the published slug explicitly
- --dry-run — preview without applying
- --json — print exactly one JSON document to stdout
- --yes — skip the confirmation prompt (non-interactive use)
Examples:
stak publish ./my-stak --slug my-stak
stak publish mainMaintenance
upgradeUpdate the STAK CLI to the newest version on your channel (`beta` for a prerelease build, `latest` for a release).
stak upgrade [--dry-run] [-y|--yes]Options:
- --dry-run — print the install command without running it
- -y, --yes — install without asking for confirmation
Examples:
stak upgrade
stak upgrade --dry-runNotes:
- Detects whether the CLI was installed with npm or pnpm and shows the exact command before running it. If the install fails, the command is printed so you can run it yourself.
stak try — precision example
stak try
Run a STAK in an isolated agent environment.
Usage:
stak try <stak> [options] -- <agent>
Supported agents: codex, claude, cursor
Examples:
stak try @owner/name -- codex
stak try @owner/name --dry-run -- claude
stak try @owner/name -- cursor
Behavior:
- main unchanged
- normal bindings unchanged
- temporary runtime
- cleanup after sessionstak use — precision example
stak use
`use` does not launch an agent.
Typical workflow:
stak use @owner/name
stak run claude