# CLI reference

Every kuvo command, its options and what it prints.

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](/docs/installation/#the-kuvo-command) for how it gets on your PATH.

```sh
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.

```sh
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. |

```text
$ 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.

```text
$ 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](/docs/agents/#who-created-what).

## kuvo exec

Run a command in a container and stream its output.

```sh
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 `&&`:

```sh
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.

```sh
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.

```sh
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.

```text
$ 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.

```text
$ 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](/docs/app/#settings), 7 days by default.

```sh
kuvo archive bench
```

## kuvo restore

Restore an archived container and start it.

```sh
kuvo restore bench
```

## kuvo rm

Remove one or more containers now, stopping them first.

```sh
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.

```text
$ 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.

```sh
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. |