CLI reference

dockiy manages the shared server stack and deploys application repositories.

dockiy [command] [flags]

Run dockiy <command> --help for the command's built-in help.

Commands

Command	Action
setup	Create the global configuration and a server profile
config validate	Validate the configuration
server init	Initialize or reconcile the shared server stack
server status	Inspect the shared server stack
server update	Apply infrastructure changes
server doctor	Check server prerequisites
app init	Create an application from a template
app deploy	Build and deploy an application
app rollback	Restore an application release
app list	List deployed applications
app status	Inspect an application's release and containers
releases clean	Remove old release bundles
completion	Generate shell completion
help	Show command help

Global options

These options are available on every command:

Option	Description
--config <path>	Use a specific global configuration file
--color <mode>	Style DockIY output: auto (default), always, or never
-v, --verbose	Show internal progress details and command names; command arguments stay private
-h, --help	Show help

Configuration lookup uses this order:

1. --config
2. DOCKIFY_CONFIG
3. the default file in the operating system's user configuration directory

A dockiy.config.yml in the current directory can override values from the selected global configuration for commands that use a server. It may be partial and is normally ignored by Git.

Progress and terminal output

DockIY groups longer operations into sections such as Prepare, Build, Publish, Deploy, and Finalize. In a terminal, a dotted spinner shows what is happening now. Completed steps remain visible with a check mark; warnings and failures explain what needs attention. Deployment and rollback summaries identify the release and server and include elapsed time.

DockIY uses a Docker-inspired blue theme for progress and interactive prompts. Green marks success, yellow marks warnings, and red marks errors. Labels and symbols keep the output understandable without color.

# Disable DockIY colors
dockiy app deploy staging --color never

# Show extra progress details and executed command names
dockiy app deploy staging --verbose

Progress, operation summaries, warnings, and errors go to stderr. Command data, such as application lists and server status, stays on stdout. Build tools and other subprocesses retain their own output; DockIY pauses its spinner while they print or request input.

Animation is disabled when stderr is redirected, TERM=dumb, or CI is set to a nonempty value. These runs use plain progress lines. Automatic color is disabled outside a supported terminal or when NO_COLOR is set; --color always explicitly overrides automatic detection and NO_COLOR. These controls apply to DockIY output; subprocesses control their own colors.

If application startup fails, inspect the error and the application's current status before retrying: hooks may already have changed the application. If the application is running but publishing its Git release tag fails, DockIY reports that state and tells you to rerun the same deploy command to retry tagging.

Setup

dockiy setup

Create the global configuration and its initial server profile.

dockiy setup [flags]

The command is interactive when run in a terminal. Use --non-interactive for scripts. The generated file omits built-in defaults.

Option	Description
--server <name>	Initial server profile name
--ssh <alias-or-address>	SSH alias or user@address
--non-interactive	Disable prompts; requires --server and --ssh
--force	Replace an existing configuration
--compose-project-name <name>	Infrastructure Compose project; default dockiy
--remote-path <path>	Remote DockIY root; default ~/dockiy
--platform <platform>	Build platform; default linux/amd64
--registry-tunnel-port <port>	Local registry tunnel port; default 5500
--registry-remote-port <port>	Remote registry port; default 5000

The server profile selected by default_server is used by server and app commands. Setup does not modify an existing file unless --force is used.

Configuration

dockiy config validate

Validate the global configuration, server profiles, and applicable local overrides.

dockiy config validate

The command prints the selected global configuration path and the number of server profiles.

Server

All server commands use the configured default server profile.

dockiy server init

Initialize or reconcile the shared DockIY base stack.

dockiy server init [flags]

The command prompts for missing values in a terminal. When it creates a new infrastructure repository, supply --sops with public age/SSH recipients or --sops-config with your SOPS creation rules. DockIY verifies encryption and decryption locally before continuing. For an existing repository, omit both options; its own SOPS configuration and encrypted .enc.env are used. --sops and --sops-config cannot be combined.

Option	Description
--sops <recipient>	Public age or SSH recipient(s); repeat or comma-separate
--sops-config <file>	Copy SOPS creation rules for any backend; must match .enc.env
--non-interactive	Disable prompts; require all values without defaults
--acme-email <email>	Email for Let's Encrypt certificates
--umami-host <hostname>	Public Umami hostname
--umami-password <password>	Umami administrator password
--umami-app-secret <secret>	Umami application secret; generated when omitted
--umami-postgres-db <name>	Umami database; default dockiy-umami
--umami-postgres-user <name>	Umami database user; default dockiy-umami
--umami-postgres-password <password>	Umami database password; generated when omitted
--dozzle-host <hostname>	Public Dozzle hostname
--dozzle-username <name>	Dozzle login username; default dockiy
--dozzle-password <password>	Dozzle login password
--beszel-host <hostname>	Public Beszel hostname
--beszel-email <email>	Beszel administrator email
--beszel-password <password>	Beszel administrator password

Secret values passed as flags can appear in shell history or process listings. Interactive input is safer.

dockiy server status

Show the configured server's deployed configuration, live services, health, and readiness checks.

dockiy server status

dockiy server update

Reconcile the local infrastructure repository with the server.

dockiy server update [flags]

Option	Description
--pull	Pull configured images before reconciling

The command does not regenerate credentials or change administrator accounts.

dockiy server doctor

Check server prerequisites and report targeted remedies without changing the server.

dockiy server doctor

Checks include Docker and Compose access, required tools, directories, certificates, disk space, ports, and configured DNS names.

Applications

Application commands read dockiy.yml from the current Git repository. Commands can run from any directory inside that repository.

Application manifest

The manifest must contain:

Field	Description
name	Application identifier
images	Image names; defaults to app
environments	default, or both staging and production
environments.<name>.host	Public application hostname
environments.<name>.compose_file	Environment Compose file
environments.<name>.secrets_file	Optional SOPS-encrypted environment file
hooks.build	Required local image-build hook
hooks.start	Required remote start hook
hooks.pre_start	Optional pre-start hook
hooks.rollback_pre_start	Optional rollback pre-start hook
hooks.healthcheck	Optional healthcheck hook

File paths must be clean relative paths. The build hook produces the configured images. DockIY exposes each image as DOCKIY_<NAME>_IMAGE, plus deployment values such as DOCKIY_APP_HOST, DOCKIY_ENVIRONMENT, DOCKIY_GIT_COMMIT, and DOCKIY_RELEASE.

dockiy app init

Create an application from a built-in template or Git URL.

dockiy app init [react|vitepress|nuxt|nuxt-betterauth|git-url] [name] [flags]

In a terminal, the command prompts for the application name first and then for a template when one was not supplied. The name becomes both the project directory and the deployment identity in dockiy.yml. Non-interactive use requires both positional arguments.

Option	Description
--sops <recipient>	Configure SOPS with public age or SSH recipient(s); repeat or comma-separate
--sops-config <file>	Copy your SOPS creation rules unchanged, including PGP, KMS, or key groups
--no-sops	Skip SOPS configuration

--sops, --sops-config, and --no-sops are mutually exclusive. Recipient setup verifies a local identity; imported rules are validated by SOPS when you encrypt your app's secrets. The template's path regex applies only to generated rules. See identity setup.

dockiy app deploy

Build and deploy an application release.

dockiy app deploy [default|staging|production] [flags]

The environment can be omitted when the manifest has only one environment.

Set confirm_deployments in the global config or local dockiy.config.yml to require Yes/No approval for any combination of default, staging, and production. It is off by default.

Option	Description
--version <version>	Exact X.Y.Z/vX.Y.Z, or patch, minor, major
--allow-dirty	Allow uncommitted changes for staging only
--allow-non-tip	Deploy an older or divergent commit already published on origin
--approve-initial-version	Approve the initial v0.1.0 release without prompting
--approve-git-push	Approve pushing an unpublished commit to origin without prompting
--replace-source	Replace a deployment owned by a different known repository

Default and production deployments require --version. A version bump uses the newest matching release tag. When no release exists, DockIY proposes v0.1.0. Staging creates a timestamp-and-commit tag and does not accept --version.

Deployments require a committed Git repository. The CLI builds locally, uploads images and deployment files through SSH, starts the release, and records it on the server. If the commit is not yet on the primary branch of origin, DockIY asks before pushing it. No prompt appears when the branch is already synced. Release tags are pushed automatically. Non-interactive runs that need a branch push require --approve-git-push.

dockiy app rollback

Restore an exact application release.

dockiy app rollback [default|staging|production] --to <exact-git-tag> [flags]

Option	Description
--to <tag>	Required exact Git release tag
--rebuild-if-missing	Rebuild target images missing from the server registry

Release tag formats are vX.Y.Z for default, prod/vX.Y.Z for production, and staging/<timestamp>-<commit> for staging. The environment can be omitted when the manifest has only default.

Rollback does not revert databases, volumes, migrations, or external services.

dockiy app list

List deployed applications and live Compose projects.

dockiy app list

dockiy app status

Compare recorded releases with live containers.

dockiy app status [name] [environment]

Argument	Description
name	Application name; inferred from dockiy.yml when omitted
environment	Filter by default, staging, or production

With no arguments, status uses the application in the current repository. With only a name, it reports all environments for that application.

Releases

dockiy releases clean

Remove old release directories and eligible VPS Docker and registry images while preserving the current release.

dockiy releases clean [default|staging|production] [flags]

The environment can be inferred from dockiy.yml when it defines only default. Use --app when running outside the application repository.

Option	Description
--app <name>	Application name; inferred from dockiy.yml when omitted
--keep <n>	Keep the newest n releases
--since <date>	Keep releases from YYYY-MM-DD or RFC3339 onward
--dry-run	Show what would be removed

At least one of --keep or --since is required. The current release is always kept. When both options are used, their keep rules are combined. Cleanup keeps images used by retained releases or containers. It records directory and image cleanup in the app environment's releases.json on the VPS. After deleting registry manifests, it stops the registry briefly to run garbage collection, then restarts it. Run dockiy server update before the first image cleanup so the registry permits deletion. An interrupted cleanup can be rerun.

Shell completion

dockiy completion

Generate completion scripts for a shell.

dockiy completion [bash|zsh|fish|powershell]

Supported shells:

Command	Description
dockiy completion bash	Generate Bash completion
dockiy completion zsh	Generate Zsh completion
dockiy completion fish	Generate Fish completion
dockiy completion powershell	Generate PowerShell completion

Each shell command supports:

Option	Description
--no-descriptions	Disable completion descriptions

Use dockiy completion <shell> --help for shell-specific loading commands.

Help

dockiy help

Show help for a command:

dockiy help [command]

The equivalent --help flag is available on every command.

Continue with Installation and Deploying applications.