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

Core Commands

Deploy


dockflow deploy <env> [version]

Deploy the application to the specified environment.

Option	Description
`--services <list>`	Comma-separated list of services to deploy
`--skip-build`	Skip the build phase
`--force`	Force deployment even if locked
`--skip-docker-install`	Skip Docker installation on target
`--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
`--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 executing

Build


dockflow build <environment>

Build Docker images locally without deploying.

Option	Description
`--services <list>`	Comma-separated list of services to build
`--push`	Push images to registry after build
`--skip-hooks`	Skip pre-build and post-build hooks
`--debug`	Enable debug output


dockflow build production                 # Build all services
dockflow build production --services 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.

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 directory

UI


dockflow ui

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

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


dockflow logs production              # All services
dockflow logs production app -f       # Follow specific service
dockflow logs production app -n 500   # Last 500 lines
dockflow logs production --since 1h   # Last hour

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 access

Bash


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 service

Stop


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 workers

Rollback


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 services

PS


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 command

Prune


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 images

List Commands

List Environments


dockflow list env

List 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
`--skip-docker-install`	Skip Docker installation
`--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-cli

Restart 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 via setup remote.

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 remote

Run setup on a remote Linux server from any platform.

Option	Description
`--host <host>`	Remote server IP or hostname
`--port <port>`	SSH port (default: 22)
`--user <user>`	SSH username
`--password <password>`	SSH password
`--key <path>`	Path to SSH private key
`--connection <string>`	Use existing Dockflow connection string


dockflow setup remote --host 192.168.1.10 --user root --key ~/.ssh/id_ed25519
dockflow setup remote --connection "eyJob3N0Ijoi..."

Non-Interactive Setup


dockflow setup auto

Configure a server without prompts (Linux only, must run on target host).

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.

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.

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.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 remote --host 192.168.1.10 --user root --key ~/.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