Skip to content
Eldara-TechPublic

About

A terminal UI for Docker Swarm that makes cluster state easier to see, understand, and reason about.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

24 stars

Watchers

2 watching

Forks

Latest commit

 

History

538 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

CI



SwarmCLI Logo

Swarm Management at the Speed of Thought

The terminal-UI for Docker Swarm you’ve been waiting for. Fast, keyboard-driven, and open source.

Build Status Go Report Card Latest Release License

Why SwarmCLI? • The family • Quickstart • Features • Installation • Contributing • Docs • Homepage


Visual Feast

SwarmCLI terminal UI for Docker Swarm

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.

The SwarmCLI family

SwarmCLI started as a terminal UI and grew into the toolset a Swarm team otherwise borrows from Kubernetes:

Tool What it is Kubernetes counterpart
SwarmCLI (this repo) Keyboard-driven terminal UI for Docker Swarm: stacks, services, tasks, nodes, configs, secrets, volumes, live logs, scale, rollback, exec k9s
SwarmCLI Charts Packages for Swarm stacks, installed and upgraded with swarmcli charts Helm
SwarmCLI CD GitOps continuous delivery: reconciles a swarm from Git, with drift detection, sync waves and a web UI Argo CD
RBAC proxy (Business Edition) mTLS identity, per-user roles and an audit log in front of the Docker API Kubernetes RBAC
SwarmCLI app Free phone app: health, services, nodes and logs; restart, scale and roll back —

The Community Edition is free and needs no license. The Business Edition is free on a swarm of up to three nodes.

Quickstart

Get up and running in seconds:

# macOS / Linux via Homebrew
brew install Eldara-Tech/tap/swarmcli

# Linux / macOS via the install script
curl -fsSL https://swarmcli.io/install.sh | sh -s -- ~/.local/bin

# Run it
swarmcli

Windows (Scoop), Docker and raw-binary installs are under Installation.

swarmcli is the full build: everything below, plus Business Edition's features, which stay inert until a license 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.

To turn on the Business Edition features on a swarm of up to three nodes, free:

swarmcli license activate

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.
  • Your Swarm on Your Phone: Press c for a QR code that connects the free SwarmCLI app to your swarm.
  • Keyboard First, Mouse Too: Every action has a key; the wheel, clicks and breadcrumbs work as well.
  • Zero Config: Works out-of-the-box with your local Docker engine or remote via SSH/Contexts.
  • Lightweight: Built with Go. A single static binary with no runtime dependencies, for Linux, macOS, Windows and FreeBSD.

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

# Repository
swarmcli charts repo add <name> <url>           # Add a chart repository and download its index
swarmcli charts repo list                       # List configured repositories
swarmcli charts repo update [name]              # Refresh repository indexes (all, or one)
swarmcli charts repo remove <name>              # Remove a repository

# Discovery
swarmcli charts search [keyword]                # Search charts across repositories
swarmcli charts show chart <repo/chart>         # Show chart metadata
swarmcli charts show values <repo/chart>        # Show default values.yaml
swarmcli charts show schema <repo/chart>        # Show values.schema.json

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

# Releases
swarmcli charts template <release> <chart>      # Render manifest to stdout (no deploy)
swarmcli charts install <release> <chart>       # Install a chart as a release
swarmcli charts upgrade <release> <chart>       # Upgrade a release to a new revision
swarmcli charts uninstall <release>             # Remove a release (keeps volumes)
swarmcli charts rollback <release> <rev>        # Re-deploy the contents of a past revision
swarmcli charts history <release>               # Show a release's revision history
swarmcli charts prune [release]                 # Delete old revisions beyond --history-max
swarmcli charts get values|manifest <release>   # Show stored values or rendered manifest
swarmcli charts diff upgrade <release> <chart>  # Preview manifest changes before upgrading
swarmcli charts list                            # List releases (alias: ls)
swarmcli charts status <release>                # Show release status and services

# GitOps
swarmcli charts apply -f <file>                 # Converge the swarm to a declarative release file
swarmcli charts outdated                        # Show releases with a newer chart version available

Every command takes --help, which lists that command's own options — anything else it does not read is rejected rather than quietly ignored:

swarmcli charts install --help
swarmcli charts apply -f swarmcli-release.yaml --diff   # preview, never deploys

The TUI has a read-only browser for what those commands installed: :charts lists every release with its revision, recorded status and live rollout health, expands one in place to its revision history and services, and diffs any two consecutive revisions. Everything that changes a release stays on the command line above; the view names the command for you.

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.

The SwarmCLI app

The free SwarmCLI app shows a swarm's health, its services, nodes and logs, and restarts, scales and rolls back services. It is on the App Store and coming to Google Play.

Press c in SwarmCLI, or type :connect, for a one-time QR code that adds the phone as a user on your swarm's RBAC proxy. The phone talks to the proxy directly over mutual TLS; Eldara runs no relay. Connecting needs the proxy (installed by :bootstrap) and a license on the swarm, the free one included. The app also has a built-in demo swarm, so it can be tried without connecting anything. Details in docs/mobile-app.md; screenshots at swarmcli.io/app.

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.
  • Thirteen licensed entitlements. Eight in this TUI — shell into a running service task, reveal-secret, port-forward, volumes across all nodes, RBAC user management, service health, pull progress and container statistics — and five more consumed by swarmcli-cd, because one license covers both products. See docs/features.md.

The license that turns them on need not be a paid one: the free tier grants the same features on a swarm of up to three nodes.

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 license 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. License sign-up is at swarmcli.io/be.

Installation

Channel Command
Homebrew (macOS / Linux) brew install Eldara-Tech/tap/swarmcli
Install script (Linux / macOS) curl -fsSL https://swarmcli.io/install.sh | sh -s -- ~/.local/bin
Scoop (Windows) scoop bucket add eldara-tech https://github.com/Eldara-Tech/scoop-bucket then scoop install swarmcli
Docker eldaratech/swarmcli:latest (linux/amd64, linux/arm64)
Raw binary archives and checksums on the Releases page

Running it from Docker needs the socket mounted; mount your contexts and config too, so they persist between runs:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME/.docker/contexts:/root/.docker/contexts" \
  -v "$HOME/.config/swarmcli:/root/.config/swarmcli" \
  eldaratech/swarmcli:latest

Every channel also carries the Apache-2.0 build as swarmcli-oss (image tag vX.Y.Z-oss). Checksum verification, the full build matrix, upgrades and the retired swarmcli-be names are in docs/installation.md.

Key Bindings

Key Action
? Show Help / Cheat Sheet
c Get the SwarmCLI phone app (:connect where a view uses c itself)
: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
:charts Browse chart releases
l View Logs
s Scale Service
r Restart Service
ctrl-c Quit

The mouse works in the lists too: the wheel moves the selection, a click selects a row and a double click opens it, as Enter does. A right click is Esc, and a click on a breadcrumb goes back to that view. In a list, hold Shift (Option in iTerm2) to select text in the terminal. Views that show text — inspect, logs, help — leave the mouse to the terminal, so text selects and copies as usual; see Mouse and text selection for what each terminal does with the wheel there. :mouse switches it off and remembers that in config.yaml, and SWARMCLI_MOUSE=off starts without it whatever the file says.

Configuration and telemetry

Every environment variable and on-disk path, for both editions, is documented in docs/configuration.md — SWARMCLI_ENV and LOG_LEVEL under Logging among them.

On startup, SwarmCLI makes one request. It checks whether a newer release is available, and reports that swarmcli was started — a random install id, the version and edition, your OS and architecture, how swarmcli was installed, and the shape of your swarm as counts (nodes, managers, services, Docker version). It does not send the names of anything: no services, images, stacks, nodes, hostnames, command arguments or IP address. Your country is derived from the connection and the address is never stored. The first run says so on screen before anything is sent — one line on the status bar, naming :telemetry, which prints all of the above on any run.

SWARMCLI_TELEMETRY=off stops the usage report and keeps the update check. SWARMCLI_TELEMETRY=none makes no outbound request at all. telemetry: off or telemetry: none in ~/.config/swarmcli/config.yaml does the same without the variable. Full detail in docs/license.md.

Development

Build from Source

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

Build and run in a container

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 .

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

Learn Docker Swarm

Guides from the SwarmCLI team at swarmcli.io/blog:

Project Hygiene

Impeccable project hygiene is the backbone of a thriving ecosystem.

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.


Built by the community for the community. Made with ❤️ for the Docker Swarm community.

About

A terminal UI for Docker Swarm that makes cluster state easier to see, understand, and reason about.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

24 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages