CLI Commands
Dockflow provides a comprehensive CLI for managing deployments and interacting with running services.
Installation
Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | bashThe 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
| Binary | Platform | Architecture |
|---|---|---|
dockflow-linux-x64 | Linux | x86_64 |
dockflow-linux-arm64 | Linux | ARM64 |
dockflow-macos-x64 | macOS | Intel |
dockflow-macos-arm64 | macOS | Apple Silicon |
dockflow-windows-x64.exe | Windows | x86_64 |
Global Options
These options are available on all commands:
| Option | Description |
|---|---|
--no-color | Disable colored output |
--verbose | Enable verbose output |
-v, --version | Show 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 hostnameport: SSH portuser: Deployment userprivateKey: SSH private keypassword: 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.
| Option | Description |
|---|---|
--only <list> | Comma-separated list of services to deploy |
--skip-build | Skip the build phase |
--force | Force deployment even if locked |
--accessories | Deploy only accessories (force redeploy) |
--all | Deploy app + force redeploy accessories |
--skip-accessories | Skip accessories check entirely |
--no-failover | Disable multi-manager failover (use first manager only) |
--dry-run | Show what would be deployed without executing |
--branch <name> | Override auto-detected git branch |
--debug | Enable 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 executingBuild
dockflow build [env]Build Docker images locally without deploying. In CI, the environment is auto-detected from the git tag or branch name.
| Option | Description |
|---|---|
--only <list> | Comma-separated list of services to build |
--push | Push images to registry after build |
--skip-hooks | Skip pre-build and post-build hooks |
--branch <name> | Override auto-detected git branch |
--debug | Enable debug output |
dockflow build production # Build all services
dockflow build production --only app # Build specific service
dockflow build production --push # Build and push to registryInit
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 CIConfig
dockflow config [subcommand]Display and validate project configuration.
| Subcommand | Description |
|---|---|
show (default) | Display current configuration |
validate (alias: check) | Validate configuration files against schemas |
path | Show configuration directory path |
| Option | Applies to | Description |
|---|---|---|
--json | show, validate | Output as JSON |
--verbose | validate | Show detailed validation output |
dockflow config # Show configuration
dockflow config validate # Validate config files
dockflow config check # Same as validate
dockflow config path # Show config directoryUI
dockflow uiLaunch the Dockflow WebUI dashboard for visual management of services, topology, and logs.
| Option | Description |
|---|---|
-p, --port <port> | Port to listen on (default: 4200) |
--no-open | Do 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.
| Option | Description |
|---|---|
-f, --follow | Follow log output |
-n, --tail <lines> | Number of lines to show (default: 100) |
-T, --timestamps | Show timestamps |
--since <time> | Show logs since timestamp (e.g., 1h, 2024-01-01) |
-s, --server <name> | Target server |
-a, --all-tasks | Include logs from terminated/historical task replicas (Swarm only) |
--pick | Interactively 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 listThe --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).
| Option | Description |
|---|---|
-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 accessBash
dockflow bash <env> <service>Open an interactive shell in a container. Alias: shell.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
--sh | Use 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).
| Option | Description |
|---|---|
-s, --server <name> | Target server |
dockflow restart production # All services
dockflow restart production app # Specific serviceStop
dockflow stop <env>Stop and remove the entire stack. Prompts for confirmation.
| Option | Description |
|---|---|
-y, --yes | Skip confirmation |
-s, --server <name> | Target server |
Scale
dockflow scale <env> <service> <replicas>Scale a service to a specified number of replicas.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
dockflow scale production app 3 # Scale to 3 replicas
dockflow scale production worker 5 # Scale workersRollback
dockflow rollback <env> [service]Rollback a service to its previous version.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
dockflow rollback production app # Rollback specific service
dockflow rollback production # Rollback all servicesPS
dockflow ps <env>List running containers for the stack.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
--tasks | Show tasks instead of containers |
Version
dockflow version <env>Show the currently deployed application version.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
--json | Output as JSON |
Audit
dockflow audit <env>Show deployment audit log (who deployed what and when).
| Option | Description |
|---|---|
-s, --server <name> | Target server |
-n, --lines <number> | Number of entries to show (default: 20) |
--all | Show all entries |
--json | Output as JSON |
Metrics
dockflow metrics <env>Show deployment metrics and statistics.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
--history | Show deployment history |
-n, --lines <number> | Number of history entries (default: 20) |
--json | Output as JSON |
--prune | Remove old metrics (keep last 1000) |
Diagnose
dockflow diagnose <env>Diagnose deployment issues and show why containers may not be starting.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
-v, --verbose | Show all diagnostic details |
Details
dockflow details <env>Show stack overview with services, replicas, and resource usage.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
SSH
dockflow ssh <env> [command...]Open an interactive SSH session or execute a command on the server.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
dockflow ssh production # Interactive session
dockflow ssh production "docker ps" # Run remote commandPrune
dockflow prune <env>Remove unused Docker resources from the server.
| Option | Description |
|---|---|
-a, --all | Remove all unused images, not just dangling |
--images | Prune images only |
--containers | Prune containers only |
--volumes | Prune volumes only |
--networks | Prune networks only |
-y, --yes | Skip 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 imagesList Commands
List Environments
dockflow list envList available environments and their servers. Aliases: envs, environments.
| Option | Description |
|---|---|
--json | Output as JSON |
List Services
dockflow list services <env>List services in a deployed stack. Alias: svc.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
-t, --tasks | Show individual tasks for each service |
--json | Output as JSON |
List Images
dockflow list images <env>Show application images on the server.
| Option | Description |
|---|---|
-s, --server <name> | Target server |
-a, --all | Show all images, not just app images |
Lock Commands
Manage deployment locks to prevent concurrent deployments.
Acquire Lock
dockflow lock acquire <env>| Option | Description |
|---|---|
-s, --server <name> | Target server |
-m, --message <msg> | Lock reason |
--force | Force acquire even if already locked |
Lock Status
dockflow lock status <env>| Option | Description |
|---|---|
-s, --server <name> | Target server |
Release Lock
dockflow lock release <env>| Option | Description |
|---|---|
-s, --server <name> | Target server |
--force | Force 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]| Option | Description |
|---|---|
--debug | Enable debug output |
List Accessories
dockflow accessories list <env> # or: dockflow acc ls <env>| Option | Description |
|---|---|
-s, --server <name> | Target server |
--json | Output as JSON |
Accessories Logs
dockflow accessories logs <env> [service]| Option | Description |
|---|---|
-f, --follow | Follow log output |
-n, --tail <lines> | Number of lines (default: 100) |
--since <time> | Show logs since timestamp |
--timestamps | Show timestamps |
--raw | Raw 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).
| Option | Description |
|---|---|
-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-cliRestart Accessories
dockflow accessories restart <env> [service]| Option | Description |
|---|---|
--force | Force restart even if updating |
-s, --server <name> | Target server |
Stop Accessories
dockflow accessories stop <env> [service]Scale accessories to 0 replicas (keeps volumes).
| Option | Description |
|---|---|
-y, --yes | Skip confirmation |
-s, --server <name> | Target server |
Remove Accessories
dockflow accessories remove <env> # or: dockflow acc rm <env>Remove the accessories stack entirely.
| Option | Description |
|---|---|
-v, --volumes | Also remove volumes (DESTRUCTIVE) |
-y, --yes | Skip 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 setupRun 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.
| Option | Description |
|---|---|
-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-keyConfigure a server without prompts (Linux only, must run on target host). Pass flags directly instead of using the interactive wizard.
| Option | Description |
|---|---|
--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-key | Generate new SSH key |
--skip-docker-install | Skip Docker installation |
--portainer | Install Portainer |
--portainer-port <port> | Portainer HTTP port (default: 9000) |
--portainer-password <pw> | Portainer admin password |
--portainer-domain <domain> | Portainer domain name |
-y, --yes | Skip 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 checkVerify all required dependencies are installed.
Get Connection String
dockflow setup connectionDisplay connection string for an existing deployment user.
| Option | Description |
|---|---|
--host <host> | Server IP/hostname |
--port <port> | SSH port (default: 22) |
--user <user> | Deployment username |
--key <path> | Path to SSH private key |
Requirements
.env.dockflowwith connection strings (or CI secrets).dockflow/config.ymlwithproject_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