CLI Reference

CLI reference for the stackie command

Synopsis

stackie [OPTIONS] <COMMAND>

Global Options

Flag	Description	Default
`-d`, `--start-daemon`	Automatically start the daemon if it is not running	false
`-D`, `--debug`	Enable verbose debug output (disables styled output)	false

The --debug flag can also be set via the STACKIE_DEBUG environment variable.

Commands

Stack Lifecycle

`stackie up`

Create and start a sandbox from a stack file.

stackie up [OPTIONS]

Flag / Arg	Description	Default
`-f`, `--file <PATH>`	Stack file path (conflicts with `--stack`)	auto-discover
`-s`, `--stack <VALUE>`	Use a pre-compiled stack, e.g. `supabase` (conflicts with `--file`)	—
`-b`, `--block <NAME>`	Start a single built-in block by name. Accepts qualified (`stackie.postgres`) or unqualified (`postgres`) names. Conflicts with `--file` and `--stack`.	—
`--name <VALUE>`	Override sandbox name	—
`--sequential`	Start blocks one at a time instead of in parallel	false
`--accept-licenses`	Accept all tool licenses automatically (for CI)	false
`--fresh`	Archive existing storage and start with a new volume	false
`--clean`	Remove existing storage before starting (conflicts with `--fresh`)	false
`--ephemeral`	Use ephemeral storage (temp dir, auto-cleaned on stop)	false
`-e`, `--env <VALUE>`	Inject environment variables into all blocks (format: `KEY=VALUE`, repeatable)	—
`--no-sandbox`	Disable sandbox isolation for first-party blocks. Third-party blocks are always sandboxed.	false
`--wait`	Wait for the daemon to be ready before starting blocks	false
`-- [ARGS]...`	Pass trailing arguments to all blocks as `STACKIE_ARGS` environment variable	—

`stackie down`

Stop and remove sandboxes from a stack.

stackie down [OPTIONS]

Flag / Arg	Description	Default
`-f`, `--file <PATH>`	Stack file path (conflicts with `--stack`)	auto-discover
`-s`, `--stack <VALUE>`	Use a pre-compiled stack (conflicts with `--file`)	—
`--name <VALUE>`	Override sandbox name (must match name used in `up`)	—
`-v`, `--volumes`	Remove volumes/storage when stopping	false

Sandbox Management

`stackie ps`

List running sandboxes.

stackie ps [OPTIONS]

Flag / Arg	Description	Default
`-a`, `--all`	Show all sandboxes (not just running)	false
`-q`, `--quiet`	Only display sandbox IDs	false

`stackie run`

Run a command in a new sandbox.

stackie run [OPTIONS] <PACKAGE> [COMMAND]...

Flag / Arg	Description	Default
`<PACKAGE>`	Package to run, e.g. `postgresql:15`	—
`--name <VALUE>`	Sandbox name	—
`-p`, `--port <N>`	Publish port (repeatable)	—
`-e`, `--env <VALUE>`	Set environment variable, format `KEY=value` (repeatable)	—
`[COMMAND]...`	Command to run inside the sandbox	—

`stackie stop`

Stop one or more running sandboxes.

stackie stop <SANDBOX>...

`stackie start`

Start one or more stopped sandboxes.

stackie start <SANDBOX>...

`stackie rm`

Remove one or more sandboxes.

stackie rm [OPTIONS] <SANDBOX>...

Flag / Arg	Description	Default
`-f`, `--force`	Force removal of a running sandbox	false

`stackie logs`

Fetch the logs of a sandbox.

stackie logs [OPTIONS] <SANDBOX>

Flag / Arg	Description	Default
`<SANDBOX>`	Sandbox ID or name	—
`--stdout`	Show stdout	true
`--stderr`	Show stderr	true
`-n`, `--tail <N>`	Number of lines from the end of the logs	0 (all)
`-f`, `--follow`	Follow log output	false

`stackie inspect`

Display detailed information about a sandbox.

stackie inspect <SANDBOX>

`stackie status`

Show the status of a sandbox.

stackie status <SANDBOX>

`stackie info`

Display system-wide information.

stackie info

Blocks

`stackie blocks`

List installed blocks.

stackie blocks [OPTIONS]

Flag / Arg	Description	Default
`-a`, `--all`	Show all blocks (including unused)	false
`-q`, `--quiet`	Only display block names	false
`--no-trunc`	Don’t truncate output	false

`stackie pull`

Pull a block’s dependencies.

stackie pull [OPTIONS] <BLOCK>

Flag / Arg	Description	Default
`<BLOCK>`	Block name, e.g. `stackie.postgres`	—
`-v`, `--version <VALUE>`	Version to pull	latest
`-p`, `--path <PATH>`	Additional search paths (repeatable)	—
`--accept-licenses`	Accept tool licenses automatically	false

`stackie search`

Search available blocks.

stackie search [OPTIONS] [TERM]

Flag / Arg	Description	Default
`[TERM]`	Search term (searches block names and descriptions)	—
`--limit <N>`	Limit number of results	25
`-l`, `--long`	Long format — detailed info with platforms and sources	false
`-a`, `--all`	Show all platforms and sources	false

Pre-compiled Stacks

`stackie stacks list`

List all available pre-compiled stacks.

stackie stacks list

`stackie stacks info`

Show detailed information about a specific pre-compiled stack.

stackie stacks info <NAME>

Tools

Stackie can install isolated versions of development tools (Node.js, Python, Go, etc.) to ~/.stackie/tools/. These don’t interfere with system installations.

`stackie tool list`

List installed tools and their versions.

`stackie tool install`

Install a specific version of a tool.

stackie tool install node 20
stackie tool install python 3.12

Flag / Arg	Description	Default
`<TOOL>`	Tool name (`node`, `python`, `go`, `temurin`, `erlang`)	—
`<VERSION>`	Version to install (e.g., `20` for Node.js 20.x)	—
`--accept-licenses`	Accept tool license automatically (for CI)	false

`stackie tool uninstall`

Uninstall a tool version.

stackie tool uninstall go 1.21

`stackie tool versions`

Show available versions for a tool.

stackie tool versions <TOOL>

`stackie tool info`

Show detailed information about an installed tool.

stackie tool info <TOOL> <VERSION>

Storage

Stackie persists block data in ~/.stackie/storage/.

`stackie storage list`

List all storage directories.

stackie storage list [OPTIONS]

Flag / Arg	Description	Default
`-p`, `--project <VALUE>`	Filter by project name	—
`-b`, `--block <VALUE>`	Filter by block name	—
`-a`, `--all`	Include archived storage	false

`stackie storage clean`

Clean up storage.

stackie storage clean [OPTIONS] [IDENTIFIER]

Flag / Arg	Description	Default
`[IDENTIFIER]`	Storage identifier: `project/block` or `project/block.run-xxx`	—
`--project <VALUE>`	Filter by project name	—
`--block <VALUE>`	Filter by block name	—
`--archived`	Only clean archived runs (from `--fresh`)	false
`-y`, `--yes`	Skip confirmation prompt	false
`--dry-run`	Show what would be removed without removing	false

`stackie storage du`

Show disk usage for storage.

stackie storage du [OPTIONS]

Flag / Arg	Description	Default
`-v`, `--verbose`	Show detailed per-block breakdown	false

Authentication

Manage authentication for Stackie Cloud features.

`stackie auth login`

Authenticate via browser.

stackie auth login [OPTIONS]

Flag / Arg	Description	Default
`--device-name <VALUE>`	Custom device name	hostname

`stackie auth status`

Show current authentication status.

`stackie auth logout`

Clear stored credentials.

`stackie auth devices`

List authorized devices.

Daemon Management

`stackie daemon start`

Start the Stackie daemon.

Flag / Arg	Description	Default
`--no-menu-bar`	Disable the menu bar (run as headless daemon)	false
`--disable-sandbox`	Disable lockbox sandboxing (for testing)	false

`stackie daemon stop`

Stop the Stackie daemon.

`stackie daemon status`

Show daemon status.

Orphan Management

Manage orphaned processes left over from daemon crashes.

`stackie orphans list`

List orphaned processes.

Flag / Arg	Description	Default
`-v`, `--verbose`	Verbose output	false
`-f`, `--format`	Output format	table

`stackie orphans cleanup`

Clean up orphaned processes.

Flag / Arg	Description	Default
`-f`, `--force`	Force cleanup without confirmation	false
`--dry-run`	Show what would be cleaned up	false
`-t`, `--timeout`	Timeout in seconds	10

`stackie orphans audit`

Show the PID lifecycle audit log.

Flag / Arg	Description	Default
`--sandbox <VALUE>`	Filter by sandbox ID or name	—
`-l`, `--limit <N>`	Maximum number of entries to show	50

MCP

The Stackie MCP server lets AI coding agents (Claude Code, Cursor, Gemini CLI, Codex, OpenCode) connect to your running stack for sandbox management, log access, and health monitoring.

`stackie mcp enroll`

Enroll AI agents to connect to the Stackie MCP server. Writes authentication credentials and server URL into each agent’s config file. Safe to run multiple times.

stackie mcp enroll [OPTIONS]

Flag / Arg	Description	Default
`--force`	Force re-enrollment, generating a new token	false

Updates

`stackie update`

Update stackie and stackied to the latest (or a specific) version. Downloads both binaries from the Stackie CDN, verifies SHA-256 checksums, gracefully stops the daemon, and atomically replaces the installed binaries.

stackie update [--version <VERSION>]

Flag / Arg	Description	Default
`--version <VALUE>`	Install a specific version	latest