CLI Commands Reference

Complete reference for all commands and options provided by the epd CLI.

Command Overview

The epd command line is organized into five functional categories:

Deploy & Lifecycle

Command	Usage	Description
`epd init`	`epd init [--ci]`	Initialize a new project with interactive runtime detection.
`epd setup`	`epd setup [--host <ip>]`	Provision server prerequisites, launch Traefik, install SSH keys, and run initial deploy.
`epd deploy`	`epd deploy [-d <dest>] [--dry-run]`	Build and deploy with zero-downtime blue/green switching.
`epd redeploy`	`epd redeploy [--dry-run]`	Restart current running version without rebuilding or uploading.
`epd rollback`	`epd rollback [version]`	Revert traffic to the previous version or a listed version.
`epd remove`	`epd remove [-y]`	Stop application, remove routes, and delete files from servers.

Observability & Metrics

Command	Usage	Description
`epd status`	`epd status [--json]`	Show live slots, running replicas, accessories, and route health.
`epd logs`	`epd logs [-f] [-n <num>]`	Stream and tail logs from services, accessories, or servers.
`epd top`	`epd top [--once]`	Real-time multi-server CPU, memory, and container monitor (`epd stats`).
`epd ssl`	`epd ssl [--host <ip>]`	Inspect and verify Let's Encrypt SSL/TLS certificates (`epd certs`).
`epd config`	`epd config [--raw]`	Validate and display resolved `epd.yml` configuration.
`epd docker-command`	`epd docker-command`	Output copy-pasteable `docker run` commands for debugging.

Server Management

Command	Usage	Description
`epd exec`	`epd exec -- <cmd>`	Execute a one-off command in the app's container environment.
`epd shell`	`epd shell`	Open an interactive terminal inside a live replica or accessory.
`epd lock`	`epd lock <action>`	Inspect or clear atomic deployment locks.
`epd proxy`	`epd proxy <action>`	Inspect, view logs, view routes, or restart shared Traefik proxy.
`epd maintenance`	`epd maintenance <on\|off>`	Zero-downtime 503 maintenance mode toggle.
`epd backup`	`epd backup [accessory]`	Create compressed database and volume snapshot archives.
`epd restore`	`epd restore <file>`	Restore a database or volume snapshot into a live accessory.

Cloud & Automation

Command	Usage	Description
`epd gh-action`	`epd gh-action`	Generate GitHub Actions CI/CD workflow (`epd ci`).
`epd auth`	`epd auth [subcommand]`	Manage linked Cloudflare & Hetzner credentials globally or per project.
`epd dns`	`epd dns <action>`	Check status or synchronize DNS records with Cloudflare or Hetzner.
`epd cloudflare`	`epd cloudflare <action>`	Manage Cloudflare DNS records for application domains.
`epd hetzner`	`epd hetzner <action>`	List, create, provision, or delete Hetzner Cloud servers.
`epd sevalla`	`epd sevalla <action>`	Manage Sevalla applications and managed database clusters.

Diagnostics & Tools

Command	Usage	Description
`epd doctor`	`epd doctor [--local]`	Run pre-flight health, configuration, and server connectivity diagnostics.
`epd completion`	`epd completion <shell>`	Generate shell autocompletion script (bash, zsh, fish).
`epd update`	`epd update`	Check for updates and upgrade to the latest version.

`epd init`

Interactively initializes epd.yml for the current project.

bash

epd init [options]

Options:

--name <name>: Override project name (defaults to folder name or package.json).
--mode <docker|process>: Choose deployment runtime (docker or process).
--host <ip>: Server host IP address.
--domain <domain>: Public domain to configure.
--port <port>: Internal application port (default: 3000).
--dockerfile: Automatically generate a production-ready starter Dockerfile.
--ci: Automatically generate .github/workflows/deploy.yml.

`epd doctor`

Run comprehensive pre-flight diagnostics on your local tooling, project configuration, environment secrets, and remote servers before running a deployment.

bash

epd doctor [options]

Options:

-l, --local: Only run local diagnostics (skips SSH connections to remote servers). Useful when working offline or in air-gapped environments.

Diagnostics performed:

Local environment: Runtime version, Docker CLI and daemon response, clean git tree verification, SSH client and permissions on private keys (0600).
Configuration & Secrets: Validates epd.yml schema, verifies that all declared secrets exist in .env or system environment, and checks cloud DNS token availability.
Remote servers: Validates SSH ping latency, tests passwordless sudo status, queries remote Docker daemon health, checks available disk space (df -h /), and detects active deploy locks.

`epd completion`

Generate shell autocompletion scripts for Zsh, Bash, or Fish.

bash

epd completion <bash|zsh|fish>

Setup Instructions:

ZshBashFish

bash

# Add to ~/.zshrc:
eval "$(epd completion zsh)"

# Or generate completion file:
epd completion zsh > ~/.zsh/completion/_epd

bash

# Add to ~/.bashrc:
source <(epd completion bash)

# Or save to system completions:
epd completion bash | sudo tee /etc/bash_completion.d/epd > /dev/null

bash

# Add to ~/.config/fish/config.fish:
epd completion fish | source

# Or generate completions file:
epd completion fish > ~/.config/fish/completions/epd.fish

`epd setup`

Prepares fresh servers for deployment. Installs Docker (or rsync and pm2 in process mode), creates the shared bridge network, configures Let's Encrypt Traefik reverse proxy, and runs the initial deployment.

bash

epd setup [options]

Interactive SSH Key Installation:

When running epd setup against a brand new server where SSH keys have not yet been installed, EPD prompts for the account's initial password in the terminal. It then automatically installs your public SSH key (~/.ssh/id_ed25519.pub), verifies passwordless key authentication, and configures passwordless sudo in /etc/sudoers.d/epd. You only have to enter the server password once!

Options:

--host <ip>: Run setup only on a specific host (repeatable).
--skip-deploy: Install prerequisites and start Traefik without executing the first deploy.

`epd deploy`

Executes a zero-downtime blue/green deployment. The new version starts alongside the existing live slot, passes its configured health checks, and only then does the reverse proxy seamlessly transition traffic.

bash

epd deploy [options]

Options:

--dry-run: Simulate the deployment plan without building images, making SSH connections, or altering remote servers.
-d, --destination <name>: Deploy using overlay configuration (e.g. epd.staging.yml).
--service <name>: Deploy only a specific service group (e.g. --service web).
--host <ip>: Deploy only to a specific host (repeatable).
--no-build: Skip local image build (reuse an image already present on the servers).
--version <tag>: Explicit version or git tag to deploy instead of the current commit.
--recreate-accessories: Rebuild and restart accessory containers (PostgreSQL, Redis, etc.).
--skip-health: Skip healthcheck verification (not recommended for production).
--skip-hooks: Skip pre_deploy / post_deploy lifecycle scripts.
--skip-lock: Bypass atomic deployment concurrency lock.

`epd redeploy`

Restarts the currently running version across all servers without rebuilding or re-uploading container images.

bash

epd redeploy [options]

`epd rollback`

Instantly re-routes live traffic to the previously healthy slot without re-building.

bash

# Roll back to the immediately preceding version
epd rollback

# List all deployable versions stored on the server
epd rollback --list

# Roll back to a specific version
epd rollback <version>

`epd status`

Displays the live deployment state across all configured hosts.

bash

epd status [options]

Options:

--json: Output state as structured JSON (ideal for status dashboards or CI scripts).

`epd logs`

View or follow live container or PM2 logs across replicas and hosts.

bash

epd logs [options]

Options:

-f, --follow: Follow / stream logs in real time.
-n, --lines <number>: Number of lines to show from the end of logs (default: 100).
--service <name>: Filter logs to a specific service (e.g. web or worker).
--accessory <name>: View logs from an accessory container (e.g. db).
--host <ip>: Filter logs to a specific server.
--grep <pattern>: Filter log lines matching a string or pattern.
--since <time>: Show logs since timestamp (e.g. 10m, 1h, 2026-09-08T15:00:00).

`epd exec`

Run a one-off command inside the app's container environment on the server.

bash

# Run database migrations
epd exec -- bun run db:migrate

# Open an interactive shell inside Postgres accessory
epd exec --accessory db -i -- psql -U postgres

`epd shell`

Opens an interactive shell inside a running replica container or accessory.

bash

epd shell
epd shell --accessory db
epd shell --host 203.0.113.10

`epd top`

Real-time multi-server metrics monitor (aliased as epd stats). Displays CPU %, memory consumption, container processes, network I/O, disk usage, and host load averages across all servers.

bash

epd top                             # Launch interactive streaming metrics dashboard (2s refresh)
epd top --once                      # Print a single metrics snapshot and exit
epd top --host 203.0.113.10         # Monitor a specific server

`epd ssl`

Inspect and verify Let's Encrypt SSL/TLS certificates managed by Traefik across your servers (aliased as epd certs).

bash

epd ssl                             # Display table of domains, SANs, issuers, and days remaining
epd ssl --json                      # Output certificate metadata as JSON
epd ssl --host 203.0.113.10         # Query a specific host

`epd maintenance`

Toggle or inspect zero-downtime maintenance mode for this application. Injects an instant Traefik routing override that presents a responsive 503 Maintenance page to all public visitors without stopping backend containers or dropping TLS certificates.

bash

epd maintenance status              # Check if maintenance mode is active
epd maintenance on                  # Enable maintenance mode
epd maintenance on -m "Upgrading database. Back at 15:00 UTC."
epd maintenance off                 # Disable maintenance mode and restore traffic

`epd backup`

Create compressed database and volume backups from running accessories (PostgreSQL, MySQL, MariaDB, MongoDB, or generic persistent volumes).

bash

epd backup                          # Back up all configured accessories
epd backup db                       # Back up a specific database accessory
epd backup db -o ./my-backup.sql.gz # Custom local output file path

`epd restore`

Restore a database or volume snapshot into a live running accessory.

bash

epd restore ./backups/myapp-db-2026-09-07.sql.gz
epd restore ./backups/myapp-db.sql.gz --accessory db -y # Skip confirmation prompt

`epd gh-action`

Generate a production-ready GitHub Actions deployment workflow (aliased as epd ci).

bash

epd gh-action [options]

Prompts for trigger events (push, pull_request, or both), target git branch, and destination overlay. Displays the exact repository secrets required (SSH_PRIVATE_KEY, DNS tokens, etc.).

`epd auth`

Manage linked Cloudflare and Hetzner accounts (aliased as epd login).

bash

epd auth [status|cloudflare|hetzner|logout]

`epd dns`

Manage automated DNS record synchronization with Cloudflare or Hetzner DNS.

bash

epd dns status          # Compare live DNS records against server IPs
epd dns sync            # Synchronize A/AAAA records
epd dns sync --dry-run  # Preview changes without making API requests
epd dns sync --no-proxied # Disable Cloudflare CDN orange-cloud proxy

`epd hetzner`

Manage Hetzner Cloud infrastructure directly.

bash

epd hetzner list          # List all servers in your Hetzner Cloud project
epd hetzner types         # View server specs and prices (vCPU, RAM, EUR/mo)
epd hetzner locations     # List available datacenter locations
epd hetzner create <name> # Create new VPS (e.g. --type cx22 --location fsn1)
epd hetzner create <name> --setup # Create and immediately configure with epd setup
epd hetzner delete <name> # Delete server

`epd sevalla`

Manage Sevalla cloud applications, deployments, and managed database clusters.

bash

epd sevalla list          # List all Sevalla applications
epd sevalla databases     # List managed database clusters
epd sevalla deploy <id>   # Trigger deployment of a Sevalla application

`epd lock`

Manage atomic deployment locks.

bash

epd lock status     # Who holds the deploy lock on each server; flags locks that look stale
epd lock release    # Release the deploy lock on every server (use when no deploy is running)

A lock looks stale when the process that took it is gone (same machine) or it has been held for more than 6 hours. epd lock release is the override. epd deploy --skip-lock ignores the lock for a single deploy, and should be used only with the same care.

`epd remove`

Completely tear down an application from the servers.

bash

epd remove
epd remove -y              # Non-interactive confirmation
epd remove --keep-data     # Leave persistent volume data on disk

`epd update`

Check for new releases and upgrade EPD to the latest version.

bash

epd update

CLI Commands Reference ​

Command Overview ​

Deploy & Lifecycle ​

Observability & Metrics ​

Server Management ​

Cloud & Automation ​

Diagnostics & Tools ​

epd init ​

Options: ​

epd doctor ​

Options: ​

Diagnostics performed: ​

epd completion ​

Setup Instructions: ​

epd setup ​

Interactive SSH Key Installation: ​

Options: ​

epd deploy ​

Options: ​

epd redeploy ​

epd rollback ​

epd status ​

Options: ​

epd logs ​

Options: ​

epd exec ​

epd shell ​

epd top ​

epd ssl ​

epd maintenance ​

epd backup ​

epd restore ​

epd gh-action ​

epd auth ​

epd dns ​

epd hetzner ​

epd sevalla ​

epd lock ​

epd remove ​

epd update ​

CLI Commands Reference

Command Overview

Deploy & Lifecycle

Observability & Metrics

Server Management

Cloud & Automation

Diagnostics & Tools

`epd init`

Options:

`epd doctor`

Options:

Diagnostics performed:

`epd completion`

Setup Instructions:

`epd setup`

Interactive SSH Key Installation:

Options:

`epd deploy`

Options:

`epd redeploy`

`epd rollback`

`epd status`

Options:

`epd logs`

Options:

`epd exec`

`epd shell`

`epd top`

`epd ssl`

`epd maintenance`

`epd backup`

`epd restore`

`epd gh-action`

`epd auth`

`epd dns`

`epd hetzner`

`epd sevalla`

`epd lock`

`epd remove`

`epd update`