dmctl CLI Reference

dmctl is the operator’s command-line client for a running dockmesh server. It’s a thin wrapper over the REST API — anything it does, the web UI does too. Use it when you want to script deploys, adopt existing compose projects, or just prefer a terminal over a browser.

Installation

dmctl is shipped inside the release tarball and dropped into /usr/local/bin/dmctl by the regular installer. If you installed dockmesh via:

curl -fsSL https://get.dockmesh.dev | sudo bash

…then dmctl is already on your PATH. Verify with:

dmctl --version

If you only run dockmesh servers but want dmctl on a separate machine (a workstation, a CI runner, a remote admin box), pull just the binary from the release tarball:

# macOS arm64 example — substitute the right OS/arch for your host
curl -fsSL "https://github.com/dockmesh/dockmesh/releases/latest/download/dockmesh_darwin_arm64.tar.gz" \
  | tar -xzO dmctl | sudo tee /usr/local/bin/dmctl > /dev/null
sudo chmod +x /usr/local/bin/dmctl

Release builds: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64. There is no prebuilt Windows binary — Windows operators run dmctl under WSL or build from source via go install ./cmd/dmctl.

Authentication

dmctl supports two auth modes, picked at login time.

Interactive password login (recommended for workstation use)

dmctl login http://localhost:8080 --user admin

Prompts for the password (hidden). If MFA is enabled on that account, also prompts for the 6-digit TOTP code. On success, saves access + refresh tokens to ~/.config/dmctl/config.json (mode 0600) and validates them via GET /me.

The access token is a 15-minute JWT; dmctl automatically refreshes it using the refresh token. Refresh lifetime is governed by the server’s Sessions settings under Authentication — the out-of-the-box defaults are a 24-hour absolute session and a 14-day “remember me” window. Both are configurable per deployment, so check your server’s setting if you need to plan for longer-lived CI logins.

API token login (recommended for CI / scripts)

First create a token in the UI: click your avatar in the top-right, pick API tokens, New token. Choose a role (narrow the scope as much as possible — CI typically only needs stack.deploy / read). Copy the token once shown.

Then on the machine that will use it:

# Flag (visible in shell history — avoid on shared hosts)
dmctl login https://dockmesh.example.com --token dmt_abc123

# Safer — pipe from stdin
echo "dmt_abc123" | dmctl login https://dockmesh.example.com

# Safest — from a secrets manager
vault kv get -field=dmctl_token secret/dockmesh | dmctl login https://dockmesh.example.com

API tokens don’t expire and don’t need refresh. Revoke from the UI when you’re done.

Environment variables (non-persistent)

Skip the config file entirely — useful in CI where you already have the server + token in env:

export DMCTL_SERVER=https://dockmesh.example.com
export DMCTL_TOKEN=dmt_abc123
dmctl stacks list

Commands

dmctl login <server>

See Authentication above.

Flags:

Flag	Purpose
--user <username>	Interactive password login
--token <token>	API token from flag (else read from stdin)
--insecure	Skip TLS cert verification (self-signed / lab only)

dmctl logout

Clears the saved token + refresh token. Server URL stays in the config so the next dmctl login <server> can skip the URL arg via env or reuse.

dmctl whoami

Prints the authenticated user — quick way to confirm which account / role is active.

dmctl stacks list

Lists every managed stack. Columns: name, host, deployment status.

dmctl stacks get <name>

Prints the stack’s compose.yaml + .env to stdout.

dmctl stacks deploy <name>

Runs docker compose up -d server-side. Optional --environment <name> to apply a compose overlay (compose.<name>.yaml), --host <id> for a remote host target.

dmctl stacks stop <name>

Stops the stack via docker compose down server-side. Volumes and networks are preserved.

dmctl stacks status <name>

Per-service status of a deployed stack: container ID, state, health, image.

dmctl stacks logs <name>

Streams logs from every service. Optional --service <name> to narrow. --follow / -f for live stream, --tail <N> for history depth.

dmctl stack adopt [path]

Takes over management of a running compose project. See Adopt an Existing Compose Stack for the full walkthrough.

From the directory with the compose.yaml:

cd ~/docker/audiobookshelf
dmctl stack adopt .

Flags:

Flag	Purpose
--name foo	Override stack name (default: directory basename)
--host mac-mini	Target a specific host when multi-host
--dry-run	Validate + preview only, nothing uploaded
--yes	Skip confirmation prompt — for CI
--with-env	Include .env in the bundle. Off by default because .env usually contains secrets
--max-size <bytes>	Max bundle size (default 100 MiB)

dmctl containers list

Lists containers on the target host. Pass --all / -a to include stopped containers. Use the global --host <id> flag (or --host all) to target a different host or fan out across the fleet.

dmctl containers logs <id>

Streams container logs. Flags: --follow / -f for live streaming and --tail <N> (default 100) for history depth.

dmctl containers exec <id> -- <cmd>

Opens an interactive shell / runs a command inside a container.

Container lifecycle actions (start, stop, restart, kill) aren’t shipped in dmctl yet — use the web UI or call the REST endpoints directly with curl (POST /api/v1/containers/{id}/start etc.); they’re tracked in the roadmap for a follow-up release.

dmctl backup …

Trigger and manage backup jobs — see dmctl backup --help for subcommands.

dmctl alert …

List and manage alert rules — see dmctl alert --help.

dmctl enroll …

Enroll a new remote host as an agent. Usually easier via the UI, but the CLI path is scriptable for fleet rollouts.

Global flags

Any command accepts these:

Flag	Purpose
--server <url>	Override the saved server URL for one call
--token <token>	Override the saved token for one call
--host <id>	Target a specific host (default: local or whatever host the token is scoped to)
--insecure	Skip TLS cert verification
--output json	Emit JSON instead of the human-readable table (scripting-friendly)

Plus --help on any subcommand to see its specific flags + examples.

Configuration file

Location per OS:

• Linux: ~/.config/dmctl/config.json
• macOS: ~/Library/Application Support/dmctl/config.json
• Windows: %APPDATA%\dmctl\config.json

Mode 0600, contains:

{
  "server": "https://dockmesh.example.com",
  "token": "…",
  "refresh_token": "…",
  "insecure": false
}

Edit directly if you want to point dmctl at a different server without re-running login. The refresh_token is present only when you used --user login; API-token installs omit it.

See also

• Adopt an Existing Compose Stack — the primary dmctl use case
• GitHub Actions integration — scripted deploys from CI
• API overview — everything dmctl does is one REST call away