Interactive command-line assistant that simplifies using Docker.
Instead of memorizing docker run options, answer a few questions and DockerX
builds the command for you: it displays it, asks for confirmation, then runs it.
dockerx runPrerequisites:
- Node.js 22 or newer
- Docker (
dockerCLI available in the PATH)
Docker commands need access to the Docker daemon. If your user is not in the
docker group, run DockerX with sudo — some operations (network management,
pull, run) will fail with a permission error otherwise.
npm install -g @rscomeback/dockerxIf the global install fails with a EACCES permission error (npm is not allowed
to write to /usr/local), either run it with sudo:
sudo npm install -g @rscomeback/dockerxor configure npm to install in your home directory:
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @rscomeback/dockerxThe dockerx command is then available globally. No DockerX install needed to
try it out: npx @rscomeback/dockerx open.
npm install
npm run build
npm linkThe dockerx command is then available globally.
dockerx openOpens a full-screen menu in the terminal. Navigate with the arrow keys or Tab, press Enter to select, Esc to go back:
- Pull an image — lists the first official images from the Docker Hub API.
Type to search (results update as you type), select an image and press Enter
to
docker pullit. - Run — build a
docker runcommand yourself: toggle the options you want (Image, name, ports, volumes, environment variables,-it,--detach,--rm, command) with Space, then confirm to run. - History — the last launched containers: pick one to re-run it as-is or to modify its options before re-running (see History).
- Compose — create and manage a Docker Compose project (see Docker Compose).
- Network — list, create, remove and inspect Docker networks, choosing the driver (bridge, host, none, overlay, macvlan, ipvlan).
- Exit — leave the menu.
dockerx runDockerX asks the following questions:
- Which Docker image do you want to use? (default
node:22) - Container name (optional)
- Add one or more ports? (local port, container port)
- Add volumes? (local path, path in the container)
- Add environment variables? (name, value)
- Interactive mode
-it? - Detached mode
--detach? - Command to run in the container (optional)
- Add
--rmautomatically?
DockerX then displays a summary of the generated command and asks for confirmation before running it. Answering "no" cancels without running anything.
Provide the image and options directly:
dockerx run node:22 --name my-app --port 3000:3000In non-interactive mode, the command is displayed and executed immediately (without confirmation), which makes it usable in scripts.
| Option | Description |
|---|---|
--name <name> |
Container name |
--port <local:container> |
Port mapping, repeatable |
--volume <local:container> |
Volume mapping, repeatable |
--env <KEY=value> |
Environment variable, repeatable |
-d, --detach |
Run in the background (detached mode) |
--no-rm |
Do not remove the container when it exits (disables --rm) |
--dry-run |
Print the generated command without running it |
--help |
CLI help |
--version |
CLI version |
With interactive confirmation:
dockerx runNon-interactive, with multiple ports, volumes and variables:
dockerx run node:22 \
--name my-app \
--port 3000:3000 \
--port 8080:80 \
--volume ./project:/app \
--env NODE_ENV=development \
--env PORT=3000Example of a generated command:
docker run --rm -it --name my-app -p 3000:3000 -v "/path/to/project:/app" -e NODE_ENV=development node:22dockerx run node:22 --port 3000:3000 --dry-runPrints the generated command and exits without running or checking Docker. Useful for previewing a command, especially in CI, before launching it.
dockerx network ls
dockerx network create my-net --driver macvlan
dockerx network rm my-net
dockerx network inspect my-netSupported drivers: bridge (default), host, none, overlay, macvlan,
ipvlan.
Every launched container is recorded in ~/.config/dockerx/history.json.
Failed attempts (permission error, unavailable daemon, container exiting with a
non-zero code) are recorded too, marked with failed, so you can spot them and
re-run or modify them after fixing the issue (for example with sudo).
dockerx history # list the last runs, pick one to re-run or modify
dockerx history clean # clear the historydockerx history shows the recent runs (date, image, name, flags). Selecting
one offers to re-run it as-is or to modify the options before
re-running: the run checklist opens pre-filled with the recorded settings
(image, name, ports, volumes, environment, interactive/detached/rm flags).
Create and manage a Compose project from the current directory. The generated
file is compose.yaml (or docker-compose.yml when opening an existing one).
dockerx compose # interactive menu
dockerx compose up # docker compose up -d (--no-detach for foreground)
dockerx compose down # docker compose down
dockerx compose ps # docker compose ps
dockerx compose logs # docker compose logs -f
dockerx compose config # validate and render the fileThe interactive menu lets you add, edit and remove services (image, container
name, ports, volumes, environment, interactive mode, command, depends_on,
restart policy, working directory), preview the generated YAML, and start or
stop the project. Existing compose.yaml files are parsed (js-yaml) so you can
edit them; rewriting one confirms first because sections DockerX does not
support (top-level networks, volumes, ...) would be dropped.
Creating and editing a project works without the Compose plugin; only the
execution commands (up, down, ps, logs, config) need the
docker compose v2 plugin installed (e.g. apt install docker-compose-plugin
on Debian/Ubuntu, dnf install docker-compose on Fedora/RHEL).
npm run dev # run the CLI with tsx (no compilation)
npm run build # compile TypeScript to dist/
npm start # run the compiled CLI
npm test # run the tests (vitest)
npm run lint # ESLint
npm run format # Prettier- DockerX never runs Docker without confirmation in interactive mode.
- Arguments are never concatenated into a string executed by a shell: the Docker
command is launched with an argument array via
child_process.spawn, which prevents command injection. - The command display applies shell escaping for readability only (safe copy-paste), never for execution.
- Docker's exit code is propagated, and
Ctrl+Cis forwarded to the Docker process for a clean shutdown. - Docker is checked before execution: a clear error is shown if it is not available.
- Attach a network to the run command (
--network,--network-alias) - Container management (
dockerx ps,dockerx stop,dockerx logs) - Image selection from locally available images
- Compose: attach services to custom networks,
docker compose build .envfile support- Shell completion (bash, zsh)
MIT — see the LICENSE file.