CLI reference

Every command, argument, and flag for stackcube and stackcubed.

stackcube

The engineer-facing CLI. Reads ~/.stackcube/client.yml, dials the daemon over gRPC, and authenticates each request with the configured SSH key.

init

Configure the CLI client. Writes ~/.stackcube/client.yml.

stackcube init [--server <host:port>] [--identity <path>] [--tls]
--server — daemon address (host:port). Default: localhost:9090.
--identity — path to SSH private key. Default: ~/.ssh/id_ed25519.
--tls — use TLS. Required when connecting through a reverse proxy like Caddy. Default: false.

deploy-key

Show the daemon's deploy public key. Add this read-only key to your git host so the daemon can fetch app repos over SSH.

stackcube deploy-key

create <appname>

Register a new app with the daemon. Run from inside the app's git repo — the CLI sends the repo's remote URL to the daemon. The daemon allocates a host port (or uses --port) and, if --domain is set, wires the front proxy to route that domain to the app's container on the stackcube-net network.

stackcube create <appname> [--domain <domain>] [--port <port>]
--domain — public domain for the app. Default: empty (no domain wiring).
--port — host port. Default: 0 (auto-assigned from the configured port range).
stackcube create my-api --domain api.example.com
stackcube create my-api --domain api.example.com --port 8080

config <appname>

Update an existing app's domain or port.

stackcube config <appname> [--domain <domain>] [--port <port>]
--domain — new public domain.
--port — new host port.

deploy <appname>

Deploy the current branch and commit. Runs stackcube lint first; aborts on lint errors. Streams deploy progress as the daemon fetches the commit, reads APP_PORT from the repo's .env, builds the image, runs docker compose up, and attaches containers to stackcube-net.

stackcube deploy <appname>

list

List all managed apps with name, port, status, domain, and creation date.

stackcube list

destroy <appname>

Destroy an app — tears down its Compose stack and removes it from the daemon's registry.

stackcube destroy <appname>

scaffold

Generate a stackcube-compatible docker-compose.yml and .env in the current directory. The compose file sets container_name, restart: unless-stopped, exposes ${APP_PORT}, and passes APP_PORT as an environment variable. The .env sets APP_PORT=3000 as a placeholder. Refuses to overwrite without --force.

stackcube scaffold [--name <name>] [--force]
--name — app name. Default: current directory name.
--force — overwrite existing files. Default: false.

lint

Check the current directory's compose file and .env against StackPaaS's contract. Runs automatically before stackcube deploy; can also be run on its own.

stackcube lint

Errors (block deploy, exit non-zero):

Warnings (informational, don't block deploy):

keys

Manage authorized SSH keys. Three subcommands:

keys add <name>

Authorize an SSH public key under the given name.

stackcube keys add <name> --key <ssh-pubkey> [--role admin|developer]
--key — the SSH public key (required).
--role — admin or developer. Default: developer.

keys remove <name>

Revoke an authorized key by name.

stackcube keys remove <name>

keys list

List authorized keys with name, role, fingerprint, and add date.

stackcube keys list

update

Check for and install a new signed release. Fetches the manifest from the configured update channel, verifies the sha256 and ed25519 signature against the compiled-in trust list, and atomically replaces this binary.

stackcube update [--check] [--snapshot | --latest | --version <version>]
--check — only check; don't download or apply.
--snapshot — fetch from the snapshot channel.
--latest — fetch from the latest channel.
--version — pin to a specific version (e.g. v0.4.0).

--snapshot, --latest, and --version are mutually exclusive.

Note: If stackcube was installed via Homebrew, update defers to brew update && brew upgrade stackcube instead of trying to swap the binary in place.

stackcubed

The PaaS daemon. Serves the gRPC API the CLI dials, drives Docker Compose for each app, and runs as a per-user launchd LaunchAgent on macOS.

init

Bootstrap the daemon on this host. Detects the Docker setup (Compose command + socket), creates the data directory, writes config.yml, generates the deploy key pair, registers the bootstrap admin's SSH public key, creates the stackcube-net Docker network, generates an initial Caddyfile, and starts the stackcube-proxy Caddy container on host ports 80 and 443.

stackcubed init --admin-key <pubkey> --domain <domain> [--data-dir <path>]
--admin-key — bootstrap admin's SSH public key (required).
--domain — domain Caddy listens on and reverse-proxies to the daemon's gRPC endpoint (required).
--data-dir — data directory. Default: ~/.stackcubed.

serve

Start the daemon's gRPC server in the foreground. Reads <data-dir>/config.yml if present, otherwise uses defaults. For always-on operation, install as a LaunchAgent instead (see service install).

stackcubed serve [--data-dir <path>]
--data-dir — data directory. Default: ~/.stackcubed.

service

Manage stackcubed as a macOS launchd LaunchAgent so it survives SSH logout, restarts on crash, and auto-starts at login. Because Docker runs inside the user session, stackcubed installs as a per-user LaunchAgent (not a system LaunchDaemon). For a headless server, enable auto-login on the Mac so Docker and the agent both come up after a reboot.

Note: service is macOS-only. There's no Linux equivalent today.

service install

Install and start the LaunchAgent. Copies the source binary to <data-dir>/bin/stackcubed and writes the plist. Subsequent self-updates rewrite the same canonical path.

stackcubed service install [--data-dir <path>] [--binary <path>]
--data-dir — data directory. Default: ~/.stackcubed.
--binary — source binary to install. Default: the currently running executable.

service uninstall

Stop and remove the LaunchAgent.

stackcubed service uninstall

service status

Show launchctl print output for the agent. Exits non-zero if the agent isn't loaded.

stackcubed service status

service restart

Restart the LaunchAgent (launchctl kickstart -k).

stackcubed service restart

update

Check for and install a new signed release. Same trust model as stackcube update; additionally, if the LaunchAgent is loaded, restarts it after a successful install so the new binary takes effect immediately.

stackcubed update [--check] [--snapshot | --latest | --version <version>]
--check — only check; don't download or apply.
--snapshot — fetch from the snapshot channel.
--latest — fetch from the latest channel.
--version — pin to a specific version.