---
url: /cli.md
description: Find the DockIY command and flags for a task.
---

# CLI reference

`dockiy` manages the shared server stack and deploys application repositories.

```text
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.

```sh
# 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.

```text
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.

```text
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.

```text
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.

```text
dockiy server status
```

### `dockiy server update`

Reconcile the local infrastructure repository with the server.

```text
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.

```text
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.

```text
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](/guide/installation#sops-identity).

### `dockiy app deploy`

Build and deploy an application release.

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

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

Set [`confirm_deployments`](/config/#deployment-confirmation) 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.

```text
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.

```text
dockiy app list
```

### `dockiy app status`

Compare recorded releases with live containers.

```text
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.

```text
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.

```text
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:

```text
dockiy help [command]
```

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

Continue with [Installation](/guide/installation) and [Deploying
applications](/guide/deploying-apps).