containerctl

module
v1.0.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0

README

Build Status go.mod Go version Go Reference

containerctl

A lightweight terminal UI for Docker container management, built for speed over remote SSH connections


Overview

containerctl removes the friction from managing containers over SSH. It’s a lightweight CLI that lets you instantly inspect, control, and tail logs from containers — perfect for remote servers where you want speed, not tooling overhead.

It sits as a thin layer between the Bubble Tea TUI framework and the Moby Docker client. It supports connecting to a remote Docker Engine API directly over SSH, so you can manage containers on a remote host without SSHing in manually.

TUI

cctl container list

The default view lists all containers on the connected host, with a colored dot showing each container's state. Select a container to:

  • Logs — follow its output in real time.
  • Shell — open an interactive shell inside the container.
  • Files — browse the filesystem without a shell, which also works for stopped containers and distroless images, and copy files or directories to your machine.
  • Inspect — view the container's configuration and details.
  • Stats — watch live CPU, memory and network usage.

You can also start, stop, restart, pause and remove containers. Actions run in the background so the UI stays responsive; failures are reported briefly on the status line.

Keys
Key Page Action
l containers Stream logs
t containers Open a shell in the container
f containers Browse the filesystem
i containers Inspect container details
m containers Show live resource stats
s / x containers Start / stop
r containers Restart
p / u containers Pause / unpause
d containers Remove (confirm with y)
Enter files Open directory
c files Copy file or directory to local
r inspect Refresh details
e inspect Show / hide environment values
Esc any Back to the container list
? any Toggle full help
q any Quit

The footer shows the keys available in the current view.

SSH

When --host is provided, containerctl connects to the remote Docker Engine API over SSH, tunneling all API calls through the connection. No manual SSH session is needed.

The SSH behavior is designed to mirror OpenSSH: ~/.ssh/config is read and its values take precedence over command-line arguments. Host keys are verified against ~/.ssh/known_hosts. Authentication follows the same order as OpenSSH — password prompt, SSH agent (SSH_AUTH_SOCK), or a private key file, with a passphrase prompt if the key is encrypted. A key given with --identity-file must be inside ~/.ssh.

Docker socket

Locally, cctl connects to --docker-host if given, otherwise to DOCKER_HOST, otherwise to unix:///var/run/docker.sock. With --host, --docker-host names the socket on the remote host (default /var/run/docker.sock) and of the Docker environment variables only DOCKER_API_VERSION is used. This also lets you connect to Docker API-compatible engines such as Podman.

Examples
  # Connect to local Docker
  cctl

  # Connect to local Podman
  cctl --docker-host unix:///run/user/1000/podman/podman.sock

  # Connect to remote host using default SSH settings
  cctl --host my-host

  # Connect to remote host using an SSH key
  cctl --host my-host:23 --identity-file ~/.ssh/id_rsa

  # Connect to remote host with username embedded in host and password prompted
  cctl --host username@my-host --ask-password

Install

Download the binary for your platform from the releases page.

macOS (Apple Silicon)
VERSION=v1.0.0-rc.1  # replace with the desired version
curl -LO https://github.com/Br0ce/containerctl/releases/download/${VERSION}/containerctl-${VERSION}-darwin-arm64

# Verify the checksum against the value published on the releases page
shasum -a 256 containerctl-${VERSION}-darwin-arm64

chmod +x containerctl-${VERSION}-darwin-arm64
sudo mv containerctl-${VERSION}-darwin-arm64 /usr/local/bin/cctl
cctl --version
Linux (amd64)
VERSION=v1.0.0-rc.1  # replace with the desired version
curl -LO https://github.com/Br0ce/containerctl/releases/download/${VERSION}/containerctl-${VERSION}-linux-amd64

# Verify the checksum against the value published on the releases page
sha256sum containerctl-${VERSION}-linux-amd64

chmod +x containerctl-${VERSION}-linux-amd64
sudo mv containerctl-${VERSION}-linux-amd64 /usr/local/bin/cctl
cctl --version

Install from Source

Requirements

  • Go 1.27+
git clone https://github.com/Br0ce/containerctl.git
cd containerctl
make build

The binary will be placed at ./bin/cctl.

Usage
./bin/cctl
# or
make run

Development

Install dependencies and tooling:

make setup

Available make targets:

Target Description
build Build the binary to ./bin/
run Run directly via go run
test Run tests (short, parallel)
test-v Run tests with verbose output
test-race Run tests with race detector
lint Run golangci-lint
format Format code with go fmt
tidy Tidy and vendor dependencies
clean Remove build artifacts
demo-up Start the demo containers
demo-down Remove the demo containers

License

Apache 2.0 — see LICENSE.

Directories

Path Synopsis
cmd
tui
theme
Package theme holds the colors and styles shared by the TUI panes.
Package theme holds the colors and styles shared by the TUI panes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL