CLI Reference

Synopsis

stackie [OPTIONS] <COMMAND>

Global Options

Flag	Description	Default
`-d, --start-daemon`	Automatically start the daemon if it's not running (default: daemon must be started manually with 'stackied')	—
`--wait-for-daemon`	Block and wait for the daemon to become ready (up to 2 minutes) instead	—
`-D, --debug`	Enable verbose debug output (disables styled output)	—

Commands

Command	Description
up	Create and start a sandbox from a stack file
down	Stop and remove sandboxes from a stack
stacks	List available pre-compiled stacks
ps	List running sandboxes
run	Run a command in a new sandbox
stop	Stop one or more sandboxes
start	Start one or more sandboxes
rm	Remove one or more sandboxes
logs	Fetch the logs of a sandbox
inspect	Display detailed information about a sandbox
status	Show sandbox status
info	Display system-wide information
pull	Pull a block's dependencies
blocks	List installed blocks (like `docker images`)
search	Search available blocks (like `docker search`)
source	Manage package source registrations (add/list/show/remove)
daemon	Manage the Stackie daemon
orphans	Manage orphaned processes from daemon crashes
tool	Manage stackie's portable tool installations (node, python, go, etc.)
storage	Manage persistent storage for blocks
auth	Authenticate with Stackie Cloud
mcp	Manage the MCP server integration
secrets	Manage secrets for managed or secrets-only stacks.
subscription	Manage your Stackie Cloud subscription.
help	Show help for Stackie commands
convert	Convert a `docker-compose.yml` to a Stackie stack file
version	Show Stackie version information
health	Check system health
update	Update stackie and stackied to the latest (or a specific) version
config	Get or set Stackie configuration settings

Stack Lifecycle

`stackie up`

Create and start a sandbox from a stack file

Flag / Arg	Description	Default
`-f, --file <PATH>`	Stack file (default: auto-discover)	—
`-s, --stack <VALUE>`	Use a pre-compiled stack (e.g., supabase)	—
`-b, --block <VALUE>`	Start a single built-in block by name (qualified or unqualified). Accepts both short names (`postgres`) and fully-qualified names (`stackie.postgres`). Unqualified names are automatically prefixed with `stackie.`. The block must exist in the built-in registry and must not be a dependency-only (`tool: true`) block. Conflicts with `-f`/`--file` and `-s`/`--stack`. Examples `stackie up -b postgres stackie up -b stackie.redis`	—
`--name <VALUE>`	Override sandbox name	—
`--sequential`	Start blocks sequentially instead of in parallel	—
`--accept-licenses`	Accept all tool licenses automatically (for non-interactive use)	—
`--fresh`	Create fresh storage (archives existing storage with run ID)	—
`--clean`	Remove existing storage before starting (clean slate)	—
`--ephemeral`	Use ephemeral storage (temp dir, auto-cleaned on stop)	—
`-e, --env <VALUE>...`	Inject environment variables into all blocks (format: `KEY=VALUE`) May be repeated: `-e PORT=3000 -e DEBUG=true`. Values override block defaults.	—
`<TRAILING_ARGS>`	Pass trailing arguments to all blocks as `STACKIE_ARGS` environment variable Example: `stackie up -- --watch --verbose` sets STACKIE_ARGS="--watch --verbose"	—
`--no-sandbox`	Disable lockbox sandbox isolation for first-party blocks Third-party blocks are always sandboxed regardless of this flag. Use only in trusted development environments.	—
`--wait`	Wait for the daemon to be ready before starting blocks By default, `stackie up` starts the daemon in the background and proceeds immediately to stack parsing. The daemon readiness wait is deferred until the first block needs to communicate with it. Use `--wait` to block upfront until the daemon is confirmed ready.	—

`stackie down`

Stop and remove sandboxes from a stack

Flag / Arg	Description	Default
`-f, --file <PATH>`	Stack file (default: auto-discover)	—
`-s, --stack <VALUE>`	Use a pre-compiled stack (e.g., supabase)	—
`--name <VALUE>`	Override sandbox name (must match name used in 'up')	—
`-v, --volumes`	Remove volumes/storage when stopping (like `docker rm -v`)	—

Pre-compiled Stacks

`stackie stacks`

List available pre-compiled stacks

`stackie stacks list`

List all available pre-compiled stacks

`stackie stacks info`

Show detailed information about a specific stack

Flag / Arg	Description	Default
`<NAME>`	Stack name (e.g., supabase)	—

Sandbox Management

`stackie ps`

List running sandboxes

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

`stackie run`

Run a command in a new sandbox

Flag / Arg	Description	Default
`<PACKAGE>`	Package to run (e.g., postgresql:15)	—
`--name <VALUE>`	Sandbox name	—
`-p, --port <N>`	Publish port(s) (format: 5432)	—
`-e, --env <VALUE>...`	Set environment variables (format: `KEY=value`)	—
`<COMMAND>`	Command to run	—

`stackie stop`

Stop one or more sandboxes

Flag / Arg	Description	Default
`<SANDBOXES>`	Sandbox IDs or names	—

`stackie start`

Start one or more sandboxes

Flag / Arg	Description	Default
`<SANDBOXES>`	Sandbox IDs or names	—

`stackie rm`

Remove one or more sandboxes

Flag / Arg	Description	Default
`<SANDBOXES>`	Sandbox IDs or names	—
`-f, --force`	Force the removal of a running sandbox	—

`stackie logs`

Fetch the logs of a sandbox

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

`stackie inspect`

Display detailed information about a sandbox

Flag / Arg	Description	Default
`<SANDBOX>`	Sandbox ID or name	—

`stackie status`

Show sandbox status

Flag / Arg	Description	Default
`<SANDBOX>`	Sandbox ID or name	—

`stackie info`

Display system-wide information

Blocks

`stackie pull`

Pull a block's dependencies

Accepts one or more block names. When a single block is supplied the command renders a single-source pull view with retry countdown; supplying multiple blocks (or --all) renders a multi-source view that stacks per-block progress bars and collapses rows on completion.

Flag / Arg	Description	Default
`<BLOCKS>`	Block name(s) to pull (e.g., "stackie.postgres"). Multiple names switch the renderer to `MultiPullScreen`.	—
`-v, --version <VALUE>`	Version to pull (default: latest). Applies to every block argument.	—
`-p, --path <PATH>`	Additional search paths for block YAML files (unused; daemon resolves paths)	—
`--accept-licenses`	Accept all tool licenses automatically (for non-interactive use)	—
`--all`	Pull every installable block discovered by the daemon. When set, the block argument is ignored and the multi-source `MultiPullScreen` renders a row per discovered block.	—

`stackie blocks`

List installed blocks (like docker images)

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

`stackie search`

Search available blocks (like docker search)

Flag / Arg	Description	Default
`<TERM>`	Search term (searches block names and descriptions)	—
`--limit <N>`	Limit results (default: 25)	25
`-l, --long`	Long format - show detailed info with platforms and sources on separate lines	—
`-a, --all`	Show all platforms and sources (don't filter to current system)	—

Sources

`stackie source`

Manage package source registrations (add/list/show/remove)

`stackie source list`

List all registered sources as a tree grouped by provider category.

The tree expands automatically when fewer than 20 sources are registered; otherwise the top-level category nodes start collapsed.

`stackie source show`

Show detailed information about a single source.

Displays the source name, provider category, platform support, and whether the source is system-protected or user-managed.

Flag / Arg	Description	Default
`<NAME>`	Source name (e.g., brew, npm, supercache)	—

`stackie source add`

The URL is validated up-front: https:// and http:// are accepted; file:// and other schemes are rejected. The name defaults to the URL's host component when --name is not supplied.

Flag / Arg	Description	Default
`<URL>`	Remote URL for the source manifest (must be `https://` or `http://`)	—
`--name <VALUE>`	Optional human-readable name for the source	—

`stackie source remove`

Remove a user-registered source (system sources are protected).

Prompts for confirmation by default with No as the default answer. Pass --force to skip the prompt; useful in non-interactive scripts.

Flag / Arg	Description	Default
`<NAME>`	Source name to remove	—
`--force`	Skip the confirmation prompt	—

Daemon Management

`stackie daemon`

Manage the Stackie daemon

`stackie daemon start`

Start the Stackie daemon

Flag / Arg	Description	Default
`--no-menu-bar`	Disable menu bar (run as headless daemon without GUI)	—
`--disable-sandbox`	Disable lockbox sandboxing (for testing or when sandboxing causes issues)	—

`stackie daemon stop`

Stop the Stackie daemon

`stackie daemon status`

Show daemon status

Orphan Management

`stackie orphans`

Manage orphaned processes from daemon crashes

`stackie orphans list`

List orphaned processes

Flag / Arg	Description	Default
`-v, --verbose`		—
`-f, --format <VALUE>`		table

`stackie orphans cleanup`

Clean up orphaned processes

Flag / Arg	Description	Default
`-f, --force`		—
`--dry-run`		—
`-t, --timeout <N>`		10

`stackie orphans audit`

Show PID lifecycle audit log

Flag / Arg	Description	Default
`--sandbox <VALUE>`		—
`-l, --limit <N>`		50

Tools

`stackie tool`

Manage stackie's portable tool installations (node, python, go, etc.)

Stackie can install isolated versions of development tools that are used by blocks requiring specific runtime versions. These tools are installed to ~/.stackie/tools/ and don't interfere with system installations.

Examples

stackie tool list                    # List installed tools
stackie tool install node 20         # Install Node.js 20
stackie tool install python 3.12     # Install Python 3.12
stackie tool uninstall go 1.21       # Uninstall Go 1.21

`stackie tool list`

List installed tools and their versions

Shows all tools that stackie has installed, including version numbers and installation paths.

`stackie tool install`

Install a tool at a specific version

Downloads and installs the specified tool version to ~/.stackie/tools/. The tool will be available for blocks that require it.

Supported tools: node, python, go, temurin (Java), erlang

Examples: stackie tool install node 20 stackie tool install python 3.12 stackie tool install temurin 21

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

`stackie tool uninstall`

Uninstall a tool version

Removes the specified tool version from ~/.stackie/tools/. Running blocks that depend on this tool version may stop working.

Flag / Arg	Description	Default
`<TOOL>`	Tool name (node, python, go, temurin, erlang)	—
`<VERSION>`	Version to uninstall	—

`stackie tool versions`

Show available versions for a tool

Lists the versions of a tool that can be installed.

Flag / Arg	Description	Default
`<TOOL>`	Tool name (node, python, go, temurin, erlang)	—

`stackie tool info`

Show detailed information about an installed tool

Flag / Arg	Description	Default
`<TOOL>`	Tool name (node, python, go, temurin, erlang)	—
`<VERSION>`	Version to show info for	—

Storage

`stackie storage`

Manage persistent storage for blocks

Stackie persists block data in ~/.stackie/storage/. This command allows listing, cleaning, and inspecting storage usage.

Examples

stackie storage list                 # List all storage directories
stackie storage clean --archived     # Clean up old archived storage
stackie storage du                   # Show disk usage

`stackie storage list`

List storage directories

Shows all storage directories with their size, status, and initialization date.

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

`stackie storage clean`

Remove storage directories

Cleans up storage directories with optional filters.

Examples: stackie storage clean supabase/postgres # Remove specific storage stackie storage clean --project supabase # Remove all supabase storage stackie storage clean --archived # Remove only archived runs

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)	—
`-y, --yes`	Skip confirmation prompt	—
`--dry-run`	Show what would be removed without removing	—

`stackie storage du`

Show storage disk usage

Displays disk usage summary by project and block.

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

Authentication

`stackie auth`

Authenticate with Stackie Cloud

Manage authentication for cloud features like package downloads and usage tracking.

Examples

stackie auth login                   # Authenticate via browser
stackie auth status                  # Show current auth status
stackie auth logout                  # Clear stored credentials
stackie auth devices                 # List authorized devices

`stackie auth login`

Authenticate with Stackie Cloud via browser

Opens your browser to authenticate with Stackie Cloud and stores a device token for API access.

Flag / Arg	Description	Default
`--device-name <VALUE>`	Custom device name (default: hostname)	—

`stackie auth logout`

Sign out and clear stored credentials

`stackie auth status`

Show current authentication status

`stackie auth whoami`

Show identity card (email, tier, devices, last login)

`stackie auth device`

Run an animated device-flow authentication session

Opens your browser and shows a live progress screen driven by the DeviceFlowPhase state machine. Polls until authenticated, expired, or denied.

`stackie auth devices`

List authorized devices

Shows all devices that have access to your Stackie Cloud account. You can revoke devices from the web dashboard.

MCP

`stackie mcp`

Manage the MCP server integration

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 (Claude Code, Cursor, Gemini CLI, Codex, OpenCode) to

connect to the Stackie MCP server.

Writes authentication credentials and server URL into each agent's config file. Safe to run multiple times — use --force to replace an existing token.

Examples: stackie mcp enroll # Enroll all agents (skips if already enrolled) stackie mcp enroll --force # Re-enroll and replace existing token

Flag / Arg	Description	Default
`--force`	Force re-enrollment even if already enrolled, generating a new token.	—

Secrets

`stackie secrets`

Manage secrets for managed or secrets-only stacks.

Reads and writes secrets stored in the OpenBao instance running as part of the stack. Only available for stacks started with mode: managed or mode: secrets-only in the stack YAML.

Examples

stackie secrets set dev API_KEY abc123
stackie secrets get dev API_KEY
stackie secrets list dev
stackie secrets delete dev API_KEY

Subscription

`stackie subscription`

Manage your Stackie Cloud subscription.

View your current plan, list available plans, upgrade, or open the billing portal. All subcommands except plans require authentication (stackie auth login).

Examples

stackie subscription status        # Show current tier and renewal date
stackie subscription plans         # List available plans
stackie subscription upgrade pro_monthly
stackie subscription manage        # Open billing portal

Utilities

`stackie help`

Show help for Stackie commands

Without a subcommand, renders the interactive Help screen. With a subcommand name, prints clap's built-in help text for that subcommand.

Examples

stackie help                    # Show general help screen
stackie help version            # Show help for the version command

Flag / Arg	Description	Default
`<COMMAND>`	Subcommand to show help for (shows general help if omitted)	—

`stackie convert`

Convert a docker-compose.yml to a Stackie stack file

Reads one or more Compose files and emits a stackie-stack.yml. When multiple input files are provided, they are merged left-to-right (later files override earlier ones), matching Docker Compose's own merge semantics. Each Compose service becomes a block in the output.

Examples

stackie convert -f docker-compose.yml
stackie convert -f docker-compose.yml -o stackie-stack.yml
stackie convert -f base.yml -f override.yml -o stackie-stack.yml

Flag / Arg	Description	Default
`-f, --file <PATH>`	Input compose file(s) (repeat -f to merge multiple files)	—
`-o, --output <PATH>`	Output stack file	stackie-stack.yml

Updates

`stackie version`

Show Stackie version information

Queries the running daemon for version metadata and renders a card showing the version label, channel, git commit, API version, and platform. Requires the daemon to be running.

Examples

stackie version

`stackie health`

Check system health

Queries the daemon for the health status of every subsystem (daemon, config, credentials, sources) and renders a status table.

Examples

stackie health

`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 in ~/.stackie/bin/.

Examples

stackie update                       # Update to latest
stackie update --version 0.9.0       # Install a specific version
stackie update --check               # Show daemon update status without installing

Flag / Arg	Description	Default
`-v, --version <VALUE>`	Install a specific version instead of the latest (e.g. 0.9.0).	—
`--check`	Check the daemon's current update status (does not download or install). Polls `GET /api/v1/update/status` every 30 seconds and renders an update status screen.	—

Configuration

`stackie config`

Get or set Stackie configuration settings

Examples

stackie config get channel            # Show current update channel
stackie config set channel canary     # Switch to canary channel
stackie config set channel edge --confirm  # Switch to edge (unstable)

Flag / Arg	Description	Default
`<COMMAND>`		—