CLI reference

Every command, argument, and flag for stackpaas and stackpaasd.

stackpaas

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

init

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

stackpaas 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.

stackpaas 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 stackpaas-net network.

stackpaas 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).
stackpaas create my-api --domain api.example.com
stackpaas create my-api --domain api.example.com --port 8080

config <appname>

Update an existing app's domain or port.

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

deploy <appname>

Deploy the current branch and commit. Runs stackpaas 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 stackpaas-net.

stackpaas deploy <appname>

list

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

stackpaas list

destroy <appname>

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

stackpaas destroy <appname>

scaffold

Generate a stackpaas-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.

stackpaas 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 stackpaas deploy; can also be run on its own.

stackpaas 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.

stackpaas 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.

stackpaas keys remove <name>

keys list

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

stackpaas 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.

stackpaas 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 stackpaas was installed via Homebrew, update defers to brew update && brew upgrade stackpaas instead of trying to swap the binary in place.

stackpaasd

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 stackpaas-net Docker network, generates an initial Caddyfile, and starts the stackpaas-proxy Caddy container on host ports 80 and 443.

stackpaasd 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: ~/.stackpaasd.

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).

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

service

Manage stackpaasd 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, stackpaasd 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/stackpaasd and writes the plist. Subsequent self-updates rewrite the same canonical path.

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

service uninstall

Stop and remove the LaunchAgent.

stackpaasd service uninstall

service status

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

stackpaasd service status

service restart

Restart the LaunchAgent (launchctl kickstart -k).

stackpaasd service restart

update

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

stackpaasd 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.