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 to the DB. The data directory is owned by the dockmesh service user with mode 700, so run the CLI with sudo — root bypasses the permission check and opens the same DB the running service uses.

This command rewrites the password hash and password_changed_at only — it does not clear an existing lockout. If the account is also locked from failed-login attempts, run dockmesh admin unlock --user <name> afterwards (or wait for the lockout duration to expire on its own).

If you prefer to run as the service user instead of root:

sudo -u dockmesh dockmesh admin reset-password --user admin --password 'NewSecure#2026'

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; the built-in roles are admin, operator, deployer, host-admin, viewer, and any custom role slug you’ve created via the UI is also valid.

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

This backs up the database only. For a full system snapshot (DB + stacks + CA + secrets), schedule the built-in system-backup job under Backups in the UI — it produces a single encrypted tarball that pairs with dockmesh restore below.

Restore from a system backup

dockmesh restore --from /path/to/dockmesh-system-2026-05-28.tar.gz
dockmesh restore --from … --dry-run        # preview what would land
dockmesh restore --from … --force          # overwrite a populated DB / non-empty data dir
dockmesh restore --from … --skip-sanity    # skip the post-restore sanity check (advanced)

Extracts a system-backup tarball into DOCKMESH_DB_PATH, DOCKMESH_STACKS_ROOT, and the rest of the data directory. By default it refuses to restore onto a populated install — pass --force only on a fresh host or when you really mean to overwrite. The post-restore sanity check verifies the audit hash chain still validates; --skip-sanity bypasses that and is reserved for cases where you already know what you’re getting.

The same extraction code path runs when you upload an archive through the Restore page in the UI.

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 is configured entirely through environment variables — there is no enroll subcommand. The install one-liner the UI’s Agents → New host flow generates already sets these for you. The two subcommands the agent does support are diagnostic only:

dockmesh-agent status     # Print where the agent looked for cert/key/CA + the resolved dial URL
dockmesh-agent version    # Print version + build info (also accepts `--version` / `-v`)

To enroll a fresh agent, set the env vars and start the agent (systemd unit on the agent host):

Variable	When required	Purpose
DOCKMESH_ENROLL_URL	First boot only	e.g. https://dockmesh.example.com/api/v1/agents/enroll
DOCKMESH_TOKEN	First boot only	The one-time token from dockmesh enroll create --name <host> (or the UI)
DOCKMESH_AGENT_URL	Optional override	e.g. wss://dockmesh.example.com:8443/connect — derived from enrolment response if omitted
DOCKMESH_DATA_DIR	Optional	Where cert/key/CA/state are persisted; defaults to /var/lib/dockmesh

After the first successful boot the agent persists its cert + URL into DOCKMESH_DATA_DIR, and you can remove DOCKMESH_ENROLL_URL + DOCKMESH_TOKEN from the env file (restarts thereafter use the persisted cert).

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

See also

• Installation — initial setup
• Upgrade Guide — safe upgrade procedure
• Environment Variables Reference — all env vars