kamal-tools

An interactive terminal TUI for managing apps deployed with Kamal 2. Connect to any server over SSH and inspect, tail logs, or destroy apps — no project deploy.yml required.

Zero runtime dependencies. Node.js built-ins only.

Requirements

• Node.js 18+
• SSH access to a server running Kamal 2

Installation

npm install -g kamal-tools

Or run directly using NPX

npx kamal-tools

Usage

Interactive TUI

kamal-tools [email protected]

Or set the host via environment variable and omit it from the command:

export [email protected]
kamal-tools

On launch, kamal-tools connects to the server over SSH, discovers all Kamal-managed apps, and presents them as a navigable menu. Select an app to open its action submenu.

Main menu navigation:

| Key | Action | |-----|--------| | ↑ / ↓ | Navigate | | Enter | Select | | Esc | Quit |

App actions:

| Action | Description | |--------|-------------| | Info | Show containers, images, and volumes for the app | | Logs | Tail live logs from the most recently started container | | Destroy | Stop and remove all containers, images, and volumes |

Global actions (below the app list):

| Action | Description | |--------|-------------| | Prune | Remove stopped containers and dangling images server-wide | | Show Kamal proxy status | List all apps routed through kamal-proxy |

Non-interactive (scriptable) mode

Pass a command after the host to run it non-interactively and print output to stdout:

kamal-tools [email protected] list
kamal-tools [email protected] info <app>
kamal-tools [email protected] logs <app>
kamal-tools [email protected] remove <app>
kamal-tools [email protected] prune
kamal-tools [email protected] proxy

Non-interactive remove skips the confirmation prompt — the caller is responsible for confirming intent.

How apps are identified

kamal-tools identifies Kamal-managed apps by their container naming convention:

<appname>-<env>-web-<env>-<hash>
<appname>-<env>-worker-<env>-<hash>

The logical app name is everything before -web-, -worker-, or -cron-. For example:

codepilot-production-web-production-1b7dce  →  codepilot-production
infernalpizza-staging-web-staging-6e0ea9    →  infernalpizza-staging

Destroying an app

The Destroy action removes all Docker resources associated with an app:

1. Stops and removes all matching containers
2. Removes all images tagged with the app name
3. Removes all volumes matching the app name

After removal, kamal-tools queries kamal-proxy for any routes still registered for the app and offers to remove them automatically via docker exec kamal-proxy kamal-proxy remove <service>.

If you prefer to clean up the proxy manually, you can also run locally from your project directory:

kamal proxy reboot --hosts [email protected]
# or
kamal app remove

Environment variables

| Variable | Description | |----------|-------------| | KAMAL_TOOLS_SSH | Default SSH host, used when no host is passed as an argument |

License

MIT