CLI Reference

The teploy CLI is a single Go binary that deploys Docker containers to any server via SSH. Install with brew install useteploy/tap/teploy.

Global flags

These flags apply to all commands:

--host    Server host (overrides servers.yml)
--user    SSH user (default: root)
--key     Path to SSH private key
--json    Output in JSON format

Commands

Core

Command	Description
teploy init	Generate a teploy.yml config for the current project. Auto-detects docker-compose files and project settings. Use --toml for TOML format, --force to overwrite.
teploy deploy [server]	Deploy the app to a server. Builds, ships, starts with health checking, routes traffic via Caddy, stops old container. Zero downtime.
teploy rollback	Roll back to the previous deploy. Starts old containers, health checks, switches traffic, stops current containers. Use --to <hash> to roll back to a specific earlier version instead of just the immediately previous one (requires that version's containers/release still be retained — see keep_versions/keep_releases).
teploy setup <host>	Provision a server for teploy. Installs Docker, configures firewall, starts Caddy, adds server to servers.yml.
teploy validate	Check config and server readiness. Validates teploy.yml, SSH connectivity, Docker, build prerequisites, and DNS.

Deploy flags

teploy deploy [server]
  --image             Docker image to deploy (skips build)
  --version           Version identifier (default: git short hash)
  --skip-dns-check    Skip DNS validation (for proxied domains like Cloudflare)
  --parallel          Max concurrent deploys for multi-server (default: from teploy.yml or 1)
  -d, --destination   Destination overlay (e.g. staging merges teploy.staging.yml)
  --app               App name for an ad-hoc deploy (bypasses teploy.yml entirely)
  --domain            Domain for an ad-hoc deploy
  --port              Container port for an ad-hoc deploy (default: 80)
  --migrate-volumes   Auto-migrate data from foreign volume sources to teploy paths (cp -a)
  --role              Only deploy to servers.yml entries with this role
  --tag               Only deploy to servers.yml entries carrying this tag

--app runs a one-off deploy from flags alone, without a teploy.yml in the current directory — useful for scripted/templated deploys. Combine with --image, --domain, and --port.

--role/--tag filter which servers a multi-server deploy targets; combine with a rollout: block in teploy.yml for a staged canary rollout — see teploy.yml Reference.

App lifecycle

Command	Description
teploy start	Start all stopped containers for the app.
teploy stop	Stop all containers for the app.
teploy restart	Restart all containers for the app.
teploy status	Show what is running for the app -- containers, versions, ports.
teploy stats	Show CPU/RAM usage per container.
teploy health	Run a health check on the running app.
teploy logs	Tail container logs. Use --process to select process type, --lines for history count.
teploy log	Show deploy history -- deploys, rollbacks, restarts, failures. Use --last N to limit entries.

Plan, drift, and self-heal

Command	Description
teploy plan	Read-only dry-run diff of what a deploy would change (create/stop/unchanged), filtered to managed app processes. Nothing on the server is touched.
teploy drift	Read-only check for whether the live deployed state has diverged from teploy.yml since the last deploy. Use --exit-code to fail a CI step on drift.
teploy heal run	Run one bounded self-heal pass: probe the app's health, restart in place with backoff if unhealthy. Web processes only — accessories are excluded.
teploy heal enable	Install a systemd timer that runs heal run on an interval, with a retry limit rather than an unbounded restart loop.
teploy heal disable	Remove the self-heal timer.
teploy heal status	Show whether self-heal is installed and its last run outcome.

KV store

Command	Description
teploy kv get <key>	Read a value from the shared Nucleus-backed KV store.
teploy kv set <key> <value>	Write a value. Use --ttl to expire it automatically.
teploy kv del <key>	Delete a key.
teploy kv exists <key>	Check whether a key is set.
teploy kv incr <key>	Atomically increment a numeric value. Use --by for a step other than 1.
teploy kv list <glob>	List keys matching a glob pattern.

kv runs against a Nucleus accessory (--accessory, default nucleus) and is one global keyspace shared across every app that points at the same accessory — prefixes are a naming convention for your own organization, not an isolation boundary. Use it for cross-app config and feature flags, not secrets.

Scaling

Command	Description
teploy scale <count>	Deploy the app to N app-role servers and update the load balancer. Use --parallel for concurrent deploys.
teploy lock	Freeze deploys for the app. Use -m to add a reason. All deploys are blocked until teploy unlock.
teploy unlock	Release the deploy lock.
teploy maintenance on	Enable maintenance mode. Returns 503 to all visitors.
teploy maintenance off	Disable maintenance mode. Restore normal traffic.

Environment variables

Command	Description
teploy env set KEY=value [...]	Set one or more environment variables.
teploy env get KEY	Get the value of an environment variable.
teploy env list	List all environment variables. Use --reveal to show values.
teploy env unset KEY	Remove an environment variable.

Secrets

Command	Description
teploy secret set KEY=value [...]	Set one or more encrypted secrets with the local age-based provider (the default).
teploy secret get KEY	Decrypt and display a secret.
teploy secret list	List all secret keys (values masked).
teploy secret rotate KEY	Generate a new random value for a secret.

set/get/list accept --provider local|openbao; rotate stays local-only. For dynamic database credentials, per-app scoped policy, multi-node HA, and continuous audit streaming, see the dedicated Secrets page for the full OpenBao command set (teploy secret setup, put, db, audit, and more).

Accessories

Command	Description
teploy accessory list	List accessory containers. Alias: teploy acc list.
teploy accessory exec <name> [command...]	Run a one-off command in an accessory's running container, e.g. teploy accessory exec db -- psql -U postgres -c 'SELECT 1'.
teploy accessory start <name>	Start a stopped accessory container.
teploy accessory stop <name>	Stop an accessory container.
teploy accessory logs <name>	Show accessory container logs. Use --lines for history count.
teploy accessory upgrade <name> <image>	Upgrade an accessory to a new image.
teploy accessory backup <name>	Back up an accessory with a database-aware dump. Requires --bucket. Use --schedule for automated backups.
teploy accessory restore <name> <date>	Restore an accessory from a backup. Requires --bucket.
teploy accessory verify-backup <name>	Restore the latest backup (or --date) into a throwaway scratch container and verify it's actually usable — a real restore + row count for Postgres/MySQL, a real boot for Nucleus, dbsize for Redis. The running accessory is never touched. Use --json for a structured result; works from server state alone with --app + --host, no teploy.yml needed.

Backups

Command	Description
teploy backup create	Create a volume backup. Requires --bucket. Accepts --keep-last/--max-age-days to auto-prune after a successful backup.
teploy backup list	List available backups. Requires --bucket.
teploy backup restore <date>	Restore a volume backup. Requires --bucket.
teploy backup schedule <cron>	Set up automated backups on a cron schedule. Requires --bucket. Bakes in --keep-last if set.
teploy backup prune	Apply a retention policy to existing backups. Use --keep-last (a floor — the newest N are always kept) and/or --max-age-days, and --accessory to target an accessory's backups instead of the app volume.

All backup commands accept --endpoint for S3-compatible storage other than AWS (MinIO, Backblaze B2, Cloudflare R2) — credentials come from TEPLOY_S3_ACCESS_KEY/TEPLOY_S3_SECRET_KEY (falls back to AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY). With no --endpoint, ambient AWS credentials are used unchanged.

Auto-deploy

Command	Description
teploy autodeploy setup	Set up webhook auto-deploy. Uploads the teploy binary and installs a systemd-managed teploy autodeploy serve process on the server, which deploys on push using the same code path teploy deploy uses. Use --branch (default: main) and --secret for HMAC validation (auto-generated and printed if omitted).
teploy autodeploy status	Check auto-deploy status.
teploy autodeploy schedule <cron>	Install a cron job that periodically pulls the running image's tag and redeploys only if a newer digest is available — useful for pinned major-version tags (e.g. :14) that still receive patch releases.
teploy autodeploy unschedule	Remove the scheduled-redeploy cron entry.
teploy autodeploy remove	Remove auto-deploy webhook.

Preview environments

Command	Description
teploy preview deploy <branch>	Deploy a branch preview. Use --ttl for auto-expiry (default: 72h).
teploy preview list	List active previews.
teploy preview destroy <branch>	Tear down a preview environment.
teploy preview prune	Remove expired previews.

Templates

Command	Description
teploy template list	List available community templates.
teploy template info <name>	Show template details.
teploy template deploy <name>	Deploy from a template. Requires --domain. Writes a teploy.yml to the current directory.

Servers

Command	Description
teploy server add <name> <host>	Add a server to ~/.teploy/servers.yml. Use --role (app or lb) and --user.
teploy server remove <name>	Remove a server from servers.yml.
teploy server list	List all configured servers.

Registries

Command	Description
teploy registry login <registry>	Store registry credentials on the server. Supports --username, --password, or --token (stdin).
teploy registry list	Show registries with stored credentials.
teploy registry remove <registry>	Remove registry credentials from the server.

Networking

Command	Description
teploy network setup	Install the configured VPN provider on every server in servers.yml, join the mesh, and update DNS entries for cross-server communication.
teploy network join [server]	Join a single server to the VPN mesh. Use --provider (tailscale, headscale, netbird) and --auth-key.
teploy network status [server]	Show mesh connectivity between servers, or for a single server if named.
teploy network grant	Mint a time-boxed, tagged pre-auth key for Tailscale or Headscale — e.g. teploy network grant --ttl 2h --tag tag:contractor. No permanent credential is created; the key expires on its own.
teploy network grants	List active grants.
teploy network revoke <key>	Revoke a grant before it expires. On Headscale this expires the key immediately (Headscale has no key-delete operation); on Tailscale it deletes it.

Remote execution

Command	Description
teploy exec <server> <command>	Run a command on a remote server via SSH.
teploy app exec -- <command>	Run a command inside the app container (migrations, one-off scripts, etc).

Utilities

Command	Description
teploy version	Show teploy version.
teploy update	Update teploy to the latest version. Downloads from GitHub releases. Use --force to reinstall.