containerctl

module
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 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, preview files and copy them to your machine (see Files).
  • 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.

Files
cctl files pane with a preview of nginx.conf next to the listing

Browse a container's filesystem without a shell. Nothing runs inside the container, so this also works for stopped containers and distroless images.

  • Preview — press p on a file to show it next to the listing, and Tab to switch the focus between list and preview. Text is shown as plain text, other files with their type and a hex dump. On narrow terminals the preview takes the place of the list.
  • Copy — press c to copy a file or directory to your machine, like docker cp.

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 with Include, Match host and tokens such as %h, and with --system-ssh-config also /etc/ssh/ssh_config. HostName replaces the host, while a username, port or identity file given on the command line takes precedence over the config. 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.1.0  # 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.1.0  # 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