Skip to Content
⚠️ Dockflow is currently under development. Bugs may occur. Please report any issues on GitHub.
CLI Reference

CLI Commands

Dockflow provides a comprehensive CLI for managing deployments and interacting with running services.

Installation

curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | bash

The script detects your platform and architecture, downloads the binary, and adds it to your PATH.

The CLI binary is self-contained and requires no external dependencies for most commands. Use dockflow setup on the target Linux host, or dockflow setup user@host from any platform to configure a remote server via SSH.

Available Binaries

BinaryPlatformArchitecture
dockflow-linux-x64Linuxx86_64
dockflow-linux-arm64LinuxARM64
dockflow-macos-x64macOSIntel
dockflow-macos-arm64macOSApple Silicon
dockflow-windows-x64.exeWindowsx86_64

Global Options

These options are available on all commands:

OptionDescription
--no-colorDisable colored output
--verboseEnable verbose output
-v, --versionShow CLI version

Connection Configuration

App commands require connection strings configured as CI secrets or in .env.dockflow for local development:

# .env.dockflow (for local CLI usage) PRODUCTION_MAIN_SERVER_CONNECTION=eyJob3N0Ijoi... # Base64-encoded JSON STAGING_STAGING_SERVER_CONNECTION=eyJob3N0Ijoi...

The connection string is generated by dockflow setup and contains:

  • host: Server IP or hostname
  • port: SSH port
  • user: Deployment user
  • privateKey: SSH private key
  • password: User password (optional)

Server names use underscores in secrets. A server named main_server in servers.yml uses MAIN_SERVER in the secret name.

All commands that accept an <env> argument support prefix matching: type pr instead of production, st instead of staging, etc. If the prefix is ambiguous, Dockflow will list the matching environments.

Core Commands

Deploy

dockflow deploy [env] [version]

Deploy the application to the specified environment. In CI, both env and version are auto-detected from the git tag or branch name.

OptionDescription
--only <list>Comma-separated list of services to deploy
--skip-buildSkip the build phase
--forceForce deployment even if locked
--accessoriesDeploy only accessories (force redeploy)
--allDeploy app + force redeploy accessories
--skip-accessoriesSkip accessories check entirely
--no-failoverDisable multi-manager failover (use first manager only)
--dry-runShow what would be deployed without executing
--branch <name>Override auto-detected git branch
--debugEnable debug output

By default, Dockflow checks if accessories.yml has changed and automatically deploys accessories when needed. Use --skip-accessories to disable this.

dockflow deploy production 1.0.0 # Deploy specific version dockflow deploy staging # Auto-generated version dockflow deploy production --accessories # Force redeploy accessories only dockflow deploy production --all # Deploy app + accessories dockflow deploy production --dry-run # Preview without executing

Build

dockflow build [env]

Build Docker images locally without deploying. In CI, the environment is auto-detected from the git tag or branch name.

OptionDescription
--only <list>Comma-separated list of services to build
--pushPush images to registry after build
--skip-hooksSkip pre-build and post-build hooks
--branch <name>Override auto-detected git branch
--debugEnable debug output
dockflow build production # Build all services dockflow build production --only app # Build specific service dockflow build production --push # Build and push to registry

Init

dockflow init [platform]

Initialize the .dockflow/ folder structure with configuration files and CI/CD setup.

dockflow init # Interactive platform selection dockflow init github # GitHub Actions dockflow init gitlab # GitLab CI

Config

dockflow config [subcommand]

Display and validate project configuration.

SubcommandDescription
show (default)Display current configuration
validate (alias: check)Validate configuration files against schemas
pathShow configuration directory path
OptionApplies toDescription
--jsonshow, validateOutput as JSON
--verbosevalidateShow detailed validation output
dockflow config # Show configuration dockflow config validate # Validate config files dockflow config check # Same as validate dockflow config path # Show config directory

UI

dockflow ui

Launch the Dockflow WebUI dashboard for visual management of services, topology, and logs.

OptionDescription
-p, --port <port>Port to listen on (default: 4200)
--no-openDo not open browser automatically

App Commands

These commands interact with deployed services via SSH. Most accept -s, --server <name> to target a specific server (defaults to the first server for the environment).

Logs

dockflow logs <env> [service]

View logs from running services. On Swarm, only currently running task replicas are streamed by default — terminated and crashed replicas are excluded to avoid interleaved noise from past failures. Use --all-tasks to include them, or --pick to select one specific replica interactively.

OptionDescription
-f, --followFollow log output
-n, --tail <lines>Number of lines to show (default: 100)
-T, --timestampsShow timestamps
--since <time>Show logs since timestamp (e.g., 1h, 2024-01-01)
-s, --server <name>Target server
-a, --all-tasksInclude logs from terminated/historical task replicas (Swarm only)
--pickInteractively pick which task replica to follow (Swarm only)
dockflow logs production # All services, running replicas only dockflow logs production app -f # Follow specific service dockflow logs production app -n 500 # Last 500 lines dockflow logs production --since 1h # Last hour dockflow logs production app --all-tasks # Include crashed/old replicas dockflow logs production app --pick # Pick a replica from a list

The --pick picker lists every task (running + history) with its current state, replica index, node, and any error message — useful for inspecting why a specific replica crashed.

Exec

dockflow exec <env> <service> [command...]

Execute a command inside a running container (default: bash).

OptionDescription
-s, --server <name>Target server
-u, --user <user>Run as specified user
-w, --workdir <dir>Working directory inside container
dockflow exec production app bash # Interactive shell dockflow exec production app "ls -la" # Run command dockflow exec production db "psql -U user" # Database access

Bash

dockflow bash <env> <service>

Open an interactive shell in a container. Alias: shell.

OptionDescription
-s, --server <name>Target server
--shUse sh instead of bash
dockflow bash production app # Open bash shell dockflow shell production app --sh # Use sh (Alpine containers)

Restart

dockflow restart <env> [service]

Force restart services (rolling update).

OptionDescription
-s, --server <name>Target server
dockflow restart production # All services dockflow restart production app # Specific service

Stop

dockflow stop <env>

Stop and remove the entire stack. Prompts for confirmation.

OptionDescription
-y, --yesSkip confirmation
-s, --server <name>Target server

Scale

dockflow scale <env> <service> <replicas>

Scale a service to a specified number of replicas.

OptionDescription
-s, --server <name>Target server
dockflow scale production app 3 # Scale to 3 replicas dockflow scale production worker 5 # Scale workers

Rollback

dockflow rollback <env> [service]

Rollback a service to its previous version.

OptionDescription
-s, --server <name>Target server
dockflow rollback production app # Rollback specific service dockflow rollback production # Rollback all services

PS

dockflow ps <env>

List running containers for the stack.

OptionDescription
-s, --server <name>Target server
--tasksShow tasks instead of containers

Version

dockflow version <env>

Show the currently deployed application version.

OptionDescription
-s, --server <name>Target server
--jsonOutput as JSON

Audit

dockflow audit <env>

Show deployment audit log (who deployed what and when).

OptionDescription
-s, --server <name>Target server
-n, --lines <number>Number of entries to show (default: 20)
--allShow all entries
--jsonOutput as JSON

Metrics

dockflow metrics <env>

Show deployment metrics and statistics.

OptionDescription
-s, --server <name>Target server
--historyShow deployment history
-n, --lines <number>Number of history entries (default: 20)
--jsonOutput as JSON
--pruneRemove old metrics (keep last 1000)

Diagnose

dockflow diagnose <env>

Diagnose deployment issues and show why containers may not be starting.

OptionDescription
-s, --server <name>Target server
-v, --verboseShow all diagnostic details

Details

dockflow details <env>

Show stack overview with services, replicas, and resource usage.

OptionDescription
-s, --server <name>Target server

SSH

dockflow ssh <env> [command...]

Open an interactive SSH session or execute a command on the server.

OptionDescription
-s, --server <name>Target server
dockflow ssh production # Interactive session dockflow ssh production "docker ps" # Run remote command

Prune

dockflow prune <env>

Remove unused Docker resources from the server.

OptionDescription
-a, --allRemove all unused images, not just dangling
--imagesPrune images only
--containersPrune containers only
--volumesPrune volumes only
--networksPrune networks only
-y, --yesSkip confirmation
-s, --server <name>Target server

The --volumes option permanently deletes data stored in unattached Docker volumes.

dockflow prune production # Prune all (with confirmation) dockflow prune production -y # Skip confirmation dockflow prune production --images -a # All unused images

List Commands

List Environments

dockflow list env

List available environments and their servers. Aliases: envs, environments.

OptionDescription
--jsonOutput as JSON

List Services

dockflow list services <env>

List services in a deployed stack. Alias: svc.

OptionDescription
-s, --server <name>Target server
-t, --tasksShow individual tasks for each service
--jsonOutput as JSON

List Images

dockflow list images <env>

Show application images on the server.

OptionDescription
-s, --server <name>Target server
-a, --allShow all images, not just app images

Lock Commands

Manage deployment locks to prevent concurrent deployments.

Acquire Lock

dockflow lock acquire <env>
OptionDescription
-s, --server <name>Target server
-m, --message <msg>Lock reason
--forceForce acquire even if already locked

Lock Status

dockflow lock status <env>
OptionDescription
-s, --server <name>Target server

Release Lock

dockflow lock release <env>
OptionDescription
-s, --server <name>Target server
--forceForce release without confirmation

Accessories Commands

Manage stateful services (databases, caches) with a separate lifecycle. Alias: acc. See Accessories Configuration for setup.

Deploy Accessories

dockflow accessories deploy <env> [version]
OptionDescription
--debugEnable debug output

List Accessories

dockflow accessories list <env> # or: dockflow acc ls <env>
OptionDescription
-s, --server <name>Target server
--jsonOutput as JSON

Accessories Logs

dockflow accessories logs <env> [service]
OptionDescription
-f, --followFollow log output
-n, --tail <lines>Number of lines (default: 100)
--since <time>Show logs since timestamp
--timestampsShow timestamps
--rawRaw output without formatting
-s, --server <name>Target server

Accessories Exec

dockflow accessories exec <env> <service> [command...]

Execute a command in an accessory container (default: sh).

OptionDescription
-u, --user <user>Run as specified user
--workdir <dir>Working directory
-s, --server <name>Target server
dockflow acc exec production postgres psql # Run psql dockflow acc exec production redis redis-cli # Run redis-cli

Restart Accessories

dockflow accessories restart <env> [service]
OptionDescription
--forceForce restart even if updating
-s, --server <name>Target server

Stop Accessories

dockflow accessories stop <env> [service]

Scale accessories to 0 replicas (keeps volumes).

OptionDescription
-y, --yesSkip confirmation
-s, --server <name>Target server

Remove Accessories

dockflow accessories remove <env> # or: dockflow acc rm <env>

Remove the accessories stack entirely.

OptionDescription
-v, --volumesAlso remove volumes (DESTRUCTIVE)
-y, --yesSkip confirmation
-s, --server <name>Target server

The --volumes flag permanently deletes all data. You will be prompted to type the environment name to confirm.

Setup Commands

Configure servers for deployment. Must be run on a Linux host, or use setup user@host for remote servers.

Interactive Setup

dockflow setup

Run the interactive setup wizard. On Windows/macOS, prompts to connect to a Linux server via SSH.

Remote Setup

dockflow setup user@host[:port]

Run setup on a remote Linux server from any platform.

OptionDescription
-k, --key <path>Path to SSH private key
--password <password>SSH password
--connection <string>Use existing Dockflow connection string
dockflow setup [email protected] -k ~/.ssh/id_ed25519 dockflow setup [email protected]:2222 -k ~/.ssh/id_ed25519 dockflow setup --connection "eyJob3N0Ijoi..."

Non-Interactive Setup

dockflow setup --host <ip> --user <name> --password <pwd> --generate-key

Configure a server without prompts (Linux only, must run on target host). Pass flags directly instead of using the interactive wizard.

OptionDescription
--host <host>Public IP/hostname for connection string
--port <port>SSH port (default: 22)
--user <user>Deployment username
--password <password>Password for new user or sudo
--ssh-key <path>Path to existing SSH private key
--generate-keyGenerate new SSH key
--skip-docker-installSkip Docker installation
--portainerInstall Portainer
--portainer-port <port>Portainer HTTP port (default: 9000)
--portainer-password <pw>Portainer admin password
--portainer-domain <domain>Portainer domain name
-y, --yesSkip confirmations

Initialize Swarm

dockflow setup swarm <env>

Initialize a Docker Swarm cluster for an environment. Joins all servers configured in servers.yml into the Swarm.

Initialize k3s

dockflow setup k3s <env>

Install and configure k3s on the target server for an environment.

Check Dependencies

dockflow setup check

Verify all required dependencies are installed.

Get Connection String

dockflow setup connection

Display connection string for an existing deployment user.

OptionDescription
--host <host>Server IP/hostname
--port <port>SSH port (default: 22)
--user <user>Deployment username
--key <path>Path to SSH private key

Requirements

  • .env.dockflow with connection strings (or CI secrets)
  • .dockflow/config.yml with project_name

For setup commands (on target Linux host):

  • Ansible (ansible, ansible-playbook)
  • SSH (ssh, ssh-keygen)

Full Workflow Example

# 1. Setup server dockflow setup [email protected] -k ~/.ssh/id_ed25519 # 2. Save connection string echo "PRODUCTION_MAIN_SERVER_CONNECTION=..." > .env.dockflow # 3. Initialize project dockflow init github # 4. Validate configuration dockflow config validate # 5. Build locally (optional) dockflow build production # 6. Deploy dockflow deploy production 1.0.0 # 7. Monitor dockflow logs production -f dockflow details production dockflow ps production # 8. Check version and audit dockflow version production dockflow audit production # 9. Troubleshoot dockflow diagnose production dockflow bash production app dockflow ssh production # 10. Scale dockflow scale production app 3 # 11. Rollback if needed dockflow rollback production app # 12. Manage accessories dockflow acc logs production postgres -f dockflow acc exec production postgres psql # 13. Cleanup dockflow prune production --images -a