CLI reference

The kuvo command works inside containers: run commands, open shells, copy files. It’s written to read well for people and for programs: plain output, errors on standard error, and exit codes you can rely on.

kuvo comes with the app. See The kuvo command for how it gets on your PATH.

kuvo --help          # list commands
kuvo exec --help     # help for one command
kuvo --version

Naming containers

Every command that takes a container accepts:

• its name, like shop-db-1,
• its Compose service name, like db,
• or the start of its ID, at least three characters.

If a service name or ID prefix matches more than one container, kuvo lists the matches and asks you to be more specific.

Starting Kuvo automatically

If Kuvo isn’t running, any command that needs the engine opens it in the background and waits for Docker to be ready. It prints Starting Kuvo… to standard error while it waits.

Set KUVO_NO_LAUNCH=1 to fail instead of starting the app.

kuvo new

Create a Linux container to work in.

kuvo new [<name>] [--image <image>] [--cpus <n>] [--memory <size>] [--no-network]

The container idles in /workspace until you give it commands, and stays until you archive or remove it. If you leave out the name, Docker picks one.

Option	Default	Meaning
--image	ubuntu:24.04	Image to create the container from.
--cpus	no limit	CPU limit, for example 2 or 0.5.
--memory	no limit	Memory limit, for example 2g or 512m. A plain number is megabytes.
--no-network		Turn off network access.

$ kuvo new bench --cpus 2 --memory 2g
Created bench from ubuntu:24.04.
Run commands with: kuvo exec bench <command>

kuvo ls

List containers with their image and state.

$ kuvo ls
NAME        IMAGE               STATE
shop-db-1   postgres:16-alpine  running for 3 hours
bench       ubuntu:24.04        archived, deleted in 6 days

When any container was made with kuvo new, a CREATED BY column shows who made it. See Coding agents.

kuvo exec

Run a command in a container and stream its output.

kuvo exec [-w <dir>] <container> <command>...

• With one argument, the command runs as a shell string, so pipes, && and globs work: kuvo exec bench "apt-get update && apt-get install -y ripgrep".
• With several arguments, they’re quoted like a normal command line: kuvo exec db pg_isready -U postgres.
• -w, --workdir sets the working directory. By default it’s the container’s own (/workspace for kuvo new containers).

Standard output and standard error stay separate, and kuvo exec exits with the command’s exit code, so it works in scripts and with &&:

kuvo exec bench "make test" && echo "tests passed"

kuvo shell

Open an interactive shell in a container: bash if the image has it, otherwise sh. Your terminal size and colors carry over.

kuvo shell db

If the container is stopped or archived, it’s started first. The command exits with the shell’s exit code.

kuvo cp

Copy files between your Mac and a container.

kuvo cp <path> <container>[:<dir>]     # copy a folder or file in
kuvo cp <container>:<file> <path>      # copy a file out

Copying in puts the folder or file in the container’s working directory, or in <dir> if you give one. If the folder is a git repository, files your .gitignore excludes are skipped, so node_modules and build output stay behind.

$ kuvo cp ~/code/parser bench
Copied 214 files (1.8 MB) to bench:/workspace/parser.

Copying out takes one file. If the destination is a folder, the file keeps its name.

$ kuvo cp bench:/workspace/parser/report.json ~/Downloads
Copied /workspace/parser/report.json to ~/Downloads/report.json (12 KB).

kuvo archive

Stop a container and keep it. It’s deleted after the retention period set in Settings, 7 days by default.

kuvo archive bench

kuvo restore

Restore an archived container and start it.

kuvo restore bench

kuvo rm

Remove one or more containers now, stopping them first.

kuvo rm bench scratch

Volumes are kept. To remove them too, use docker rm -v or Kuvo’s Remove with Volumes.

kuvo status

Show whether the engine is running, without starting it.

$ kuvo status
Running: Docker 29.8.2, 3 of 4 containers running.
Socket: /Users/you/.kuvo/docker.sock

Exits with code 1 if Kuvo isn’t running.

kuvo env

Print the DOCKER_HOST setting that points the docker command at Kuvo.

eval "$(kuvo env)"

Exit codes

Code	Meaning
0	Success.
1	Kuvo couldn’t do what you asked, for example the container doesn’t exist. The reason is printed on standard error.
any other	From kuvo exec and kuvo shell: the exit code of the command you ran.