CLI Reference

dockmesh ships a single binary that’s both the server and the CLI. In normal operation it runs as a daemon. The CLI subcommands are for one-off maintenance tasks.

Starting the server

dockmesh               # Default: reads env vars, starts server
dockmesh serve         # Same as above (explicit)
dockmesh --help        # Show all commands
dockmesh --version     # Print version + commit hash

CA management

Rotate the agent CA

Issue a new CA keypair and re-issue certs for all agents:

dockmesh ca rotate --reissue-all-agents

After rotation, all agents re-enroll on next connect. Old certs are revoked.

Export the CA

dockmesh ca export --out /tmp/dockmesh-ca.pem

Exports the CA public cert for configuring external systems to trust dockmesh-issued agent certs. The private key never leaves the server DB.

Importing a user-supplied CA key is not currently shipped — the self-signed CA generated on first boot is the only supported option. If your organisation mandates an external CA, open an issue describing the requirement.

Admin user

Reset admin password

Lost the admin password?

sudo dockmesh admin reset-password --user admin --password 'NewSecure#2026'
# Or omit --password to be prompted interactively:
sudo dockmesh admin reset-password --user admin

Requires filesystem access (you must be able to read the dockmesh DB). Run as root from the service’s working directory (usually /var/lib/dockmesh) so the CLI can open the same DB the running service uses. Clears any active lockout as a side effect.

Unlock a locked account

If a user (or you) got locked out by too many wrong attempts, you can clear the lockout without resetting the password:

sudo dockmesh admin unlock --user admin

This zeroes the failed-attempt counter and clears locked_until. The user keeps their existing password — useful when the lockout came from a browser autofill typo or automated retry, not an actual forgotten password.

Lockouts auto-expire after the configured duration (default 15 minutes), so unlock is optional — you can also just wait. The login error itself tells you how long is left:

account temporarily locked — try again in 13 minutes

Create additional admin

dockmesh admin create --username alice --password s3cr3t --email alice@example.com --role admin

--password is optional — omit it to be prompted interactively, or pipe the password on stdin for CI. --role defaults to viewer; use admin, operator, viewer, or any custom role slug.

List users

dockmesh admin list-users

Prints id, username, role, email, MFA status. Handy during incident response when you need to quickly confirm who has admin access without logging in.

Re-running `dockmesh init`

dockmesh init is idempotent — re-running it after the admin user exists doesn’t change the password. Instead you’ll see:

! admin 'admin' already exists — password NOT changed
! to reset it: sudo dockmesh admin reset-password --user admin --password <new>

All other init steps (data dir, env file, systemd unit) stay idempotent and safe to re-run.

Database

Run migrations manually

On boot, dockmesh auto-runs pending migrations. To run them manually (e.g. during a staged rollout):

dockmesh db migrate

Backup

dockmesh db backup --out /path/to/backup.db

Atomic SQLite snapshot via VACUUM INTO — safe to run while the server is up. The destination path must not exist yet (we refuse to clobber an existing file; rm it yourself first or pick a new name). For PostgreSQL, use native tools (pg_dump).

Agent bundle

Generate enrollment token

dockmesh enroll create --name web-01
# Prints the agent id, one-time token, and the install command
# to paste on the agent host.

Useful in scripts (Ansible, Terraform). Host tags are assigned separately after the agent comes online via the UI’s Agents page or PUT /api/v1/hosts/{id}/tags.

List agents

dockmesh enroll list

Prints id, name, status, hostname, version, last-seen. Works offline against the DB so it’s usable for diagnosing connectivity issues when the API itself is down.

Revoke a host

dockmesh enroll revoke --name web-01

Removes the agent row + associated tags. Equivalent to Agents → Delete in the UI.

Import / export

Bulk-import stacks from a compose directory (P.11.6.5)

dockmesh import compose-dir --path /home/ops/portainer-export --dry-run
dockmesh import compose-dir --path /home/ops/portainer-export

Scans the directory for subfolders containing compose.yaml / compose.yml / docker-compose.yaml / docker-compose.yml; each becomes a dockmesh stack. Subfolder names are slugified (my_app → my-app). Optional .env next to the compose file is copied along and encrypted at rest. --force overwrites existing stacks; --prefix legacy- namespaces the import so it can’t clash with existing stacks.

Tested against Portainer’s “Download compose” export, Dockge’s native layout, Coolify’s filesystem structure, and plain docker-compose directories.

Full-server export + import (stacks + users + audit + everything) is not shipped — planned for a later slice.

Diagnostic

Check connectivity

dockmesh doctor

Runs a series of checks:

Config loaded cleanly (HTTPAddr / BaseURL / agent URL sanity)
Database open + schema up-to-date + user count
Data directory exists + is writable
Docker daemon reachable (API version + engine version)
PKI material loads (CA + server cert on disk)

Outputs a coloured report with [ ok ] / [warn] / [FAIL] rows. Exit code is 0 when everything passes or only warnings fire, 1 when any FAIL hit. Good first step for troubleshooting.

Print config

dockmesh config show

Prints the effective config (all env vars + their values). Secrets are redacted.

Agent CLI

The agent binary has its own CLI:

dockmesh-agent enroll --server https://dockmesh.example.com --token <token>
dockmesh-agent status
dockmesh-agent version

Shell completions

Generate completions for your shell:

dockmesh completion bash > /etc/bash_completion.d/dockmesh
dockmesh completion zsh > ~/.zsh/completions/_dockmesh
dockmesh completion fish > ~/.config/fish/completions/dockmesh.fish