---

Visual Feast

Why SwarmCLI?

In the Kubernetes world, k9s is the gold standard for cluster management. We believe Docker Swarm users deserve the same level of quality, speed, and intuition.

"Because Swarm is not dead, it's just efficient. And it deserves better tools."

SwarmCLI translates the complexity of Docker Swarm into a sleek, keyboard-centric terminal UI. It’s built for developers who want to manage their clusters without leaving the terminal or waiting for heavy Web UIs to load.

Quickstart

Get up and running in seconds:

# macOS/Linux via Homebrew
brew tap eldara-tech/tap
brew install swarmcli

# Run it
swarmcli

swarmcli is the full build: everything below, plus Business Edition's features, which stay inert until a licence verifies. For the wholly Apache-2.0 build, install swarmcli-oss instead — same executable name, same commands. See docs/editions.md, and swarmcli version to check which one you have.

Features

• Real-time Observability: Live monitoring of Services, Tasks, Nodes, and Containers.
• Stack Awareness: Navigate your cluster hierarchically (Stacks > Services > Tasks).
• Instant Logs: No more docker service logs -f. Just press l on any service.
• Secrets & Configs: Manage, rotate, and — with Business Edition — reveal secrets for debugging.
• Management Actions: Scale, restart, remove, and update services with single keystrokes.
• Chart Package Manager: Helm-like packaging for Swarm — install, upgrade, roll back, and diff releases from chart repositories via swarmcli charts, or converge the swarm to a committed release file with swarmcli charts apply.
• Zero Config: Works out-of-the-box with your local Docker engine or remote via SSH/Contexts.
• Lightweight: Built with Go. Single static binary (< 20MB). Zero dependencies.

Charts (CLI)

A bare swarmcli launches the TUI, but a few commands run non-interactively when arguments are supplied: swarmcli version, swarmcli help, and the Helm-like chart package manager swarmcli charts <command>:

# Repositories
swarmcli charts repo add <name> <url>     # add a repo and download its index
swarmcli charts repo list                 # list configured repos
swarmcli charts repo update [name]        # refresh indexes (all, or one); install
                                          # and friends now refresh on their own
swarmcli charts repo remove <name>        # remove a repo

# Discovery
swarmcli charts search [keyword]          # search charts across repos
swarmcli charts show chart  <repo/chart>  # chart metadata (also: values, schema)

# Authoring
swarmcli charts lint <chart>                      # check a chart without deploying it

# Releases
swarmcli charts template <release> <repo/chart>   # render manifest (no deploy)
swarmcli charts install  <release> <repo/chart>   # install a chart as a release
swarmcli charts upgrade  <release> <repo/chart>   # upgrade to a new revision
swarmcli charts diff upgrade <release> <repo/chart>  # preview upgrade changes
swarmcli charts rollback <release> <revision>     # re-deploy a past revision
swarmcli charts uninstall <release>               # remove a release
swarmcli charts history <release>                 # revision history
swarmcli charts get values|manifest <release>     # stored values or rendered manifest
swarmcli charts prune [release]                   # delete old revisions beyond --history-max
swarmcli charts list                              # list releases
swarmcli charts status <release>                  # release status and services

# GitOps — converge the swarm to a file you commit
swarmcli charts apply -f swarmcli-release.yaml    # install/upgrade/skip to match the file
swarmcli charts apply -f swarmcli-release.yaml --diff   # preview, never deploys
swarmcli charts outdated                          # releases with a newer chart available

apply reads a release file pinning each release to a chart version, so the deployed state is reproducible and an automated updater (e.g. Renovate) has something concrete to bump. It never removes a release the file does not mention — it reports those instead. Releases can declare a wave, which groups the ones that go out together and makes each group converge before the next begins — so a migration that fails stops what depends on it from ever starting. See charts/README.md.

A chart can declare the swarmcli it needs (swarmcliVersion: ">= 1.13.0" in Chart.yaml). Installing it on an older build fails naming the version to upgrade to, instead of breaking somewhere inside the template; --skip-compat-check proceeds anyway. See charts/README.md.

Run swarmcli charts --help for the full command and option reference.

Business Edition

The Community Edition is the full open-source TUI. Business Edition is a commercial superset that adds:

• :bootstrap — one-command deploy of an mTLS-fronted RBAC proxy and per-node agent stack onto your existing Swarm.
• Per-user RBAC, identity by client certificate, role-gated mutation and exec.
• Interactive shell into a running service task.
• Reveal-secret for debugging.

The binary on disk is named swarmcli (BE is a strict superset of CE — same binary name, expanded feature set), so existing scripts and aliases continue to work.

It is not a separate download. The swarmcli archives, image, cask and Scoop manifest published from this repository's releases are the Business Edition build, carrying the licensed code inert; a licence turns it on. The wholly Apache-2.0 build ships beside it as swarmcli-oss. Which one you have is docs/editions.md, and swarmcli version answers it directly.

Documentation lives in docs/ — installation, license, bootstrap, RBAC, features, volumes, configuration and troubleshooting. Licence sign-up is at swarmcli.io/be.

Installation

Build from Source

git clone https://github.com/Eldara-Tech/swarmcli.git
cd swarmcli
go install

Using Docker container to build and run locally

docker build -t swarmcli-dev .
docker run --rm -it -v "$PWD":/app -v /var/run/docker.sock:/var/run/docker.sock  -w /app swarmcli-dev

or with docker compose:

docker compose run --build --rm swarmcli

Then run:

go run .

Logging

# Production (default)
$ go run .
# → writes JSON logs to  ~/.local/state/swarmcli/app.log

# Development
$ SWARMCLI_ENV=dev go run .
# → writes pretty logs to ~/.local/state/swarmcli/app-debug.log

# Optional: control verbosity
$ LOG_LEVEL=debug SWARMCLI_ENV=dev go run .

Environment variables

• SWARMCLI_ENV: dev enables pretty debug logs (default is prod).
• LOG_LEVEL: debug, info, warn, error, …
• SWARMCLI_DISABLE_VERSION_CHECK=true: disables the startup request to https://swarmcli.io/api/v1/version that checks whether a newer release is available.
• SWARMCLI_CHARTS_ALLOW_PLAINTEXT=1: allows chart repositories served over plain http://, which are refused by default (see charts/README.md).

On startup, SwarmCLI checks for a newer release by sending the current version and edition to https://swarmcli.io/api/v1/version. Set SWARMCLI_DISABLE_VERSION_CHECK=true to opt out.

Colorize log tails. Not perfect but simple:

sudo apt install ccze
tail -f ~/.local/state/swarmcli/app-debug.log | ccze -A

Integration tests

The logs for the integration tests can be enabled with:

TEST_LOG=1 ./test-setup/testenv.sh test

Key Bindings

Key	Action
?	Show Help / Cheat Sheet
:stack	Navigate to Stacks
:svc	Navigate to Services
:node	Navigate to Nodes
:config	Navigate to Config
:secret	Navigate to Secret
:network	Navigate to Networks
:volume	Navigate to Volumes
l	View Logs
s	Scale Service
r	Restart Service
ctrl-c	Quit

Project Hygiene

Impeccable project hygiene is the backbone of a thriving ecosystem.

• Contributing: We ❤️ contributions! Check our guide to get started.
• Security: Found a bug? Let us know securely.
• Code of Conduct: Expectations for our community.
• License: Apache 2.0.

Releasing

Releases are fully automated — no manual version file to update. The git tag is the single source of truth.

git tag v1.5.0
git push origin v1.5.0

Pushing a v* tag triggers the release workflow which:

1. Injects the tag into the binary via GoReleaser ldflags (-X main.version=1.5.0)
2. Builds for Linux, macOS, Windows, and FreeBSD (multiple architectures)
3. Publishes a GitHub release with auto-generated changelog
4. Pushes a multi-arch Docker image to Docker Hub
5. Updates the Homebrew tap and Scoop bucket

A tag here publishes the -oss half of a release — swarmcli-oss_* archives, checksums-oss.txt, eldaratech/swarmcli:<tag>-oss, and the swarmcli-oss cask and manifest. The unsuffixed names and :latest belong to the Business Edition build, which is tagged in a second repository at the same version and published into this same GitHub release. RELEASING.md is the procedure; docs/editions.md is what the two artefacts are.

The in-app Version: header reads from the injected value. Local builds without GoReleaser show dev.

---