---
title: "vakna list: list boxes"
description: "List boxes."
command: "vakna list"
generated: scripts/generate.ts
verified:
  cli: "0.0.0-mock"
  date: "2026-10-20"
---

`vakna list`: list boxes.

## Synopsis

```sh
vakna list
```

Also `vakna ls`.

## Flags

| Flag | Default | What it does |
| -- | -- | -- |
| `-q, --quiet` | `off` | names only |
| `--format <format>` | `text` | text, or json: one JSON object per line |
| `--json` | `off` | the same as --format json |
| `-h, --help` | `off` | this help |

## Examples

### Example

```sh
$ vakna list
```

```prints
NAME                      STATE      AGE
api                       running    3h
worker                    running    1d
web                       running    5h
docs                      suspended  4d
prove-hypothesis-42-0137  running    3m
prove-hypothesis-42-0588  running    3m
prove-hypothesis-42-0412  running    3m
```

Exit code 0.

### Another example

```sh
$ vakna ls --format json | jq -r .name
```

```prints
api
worker
web
docs
prove-hypothesis-42-0137
prove-hypothesis-42-0588
prove-hypothesis-42-0412
```

Exit code 0.

### When it fails

```sh
$ vakna list --format yaml
```

```prints
vakna: unknown --format yaml
hint: vakna --help  # text or json
```

Exit code 2.

## Exit codes

| Code | Meaning |
| -- | -- |
| 0 | ok |
| 1 | vakna failed; under shell, run, try or fork, the command in the box failed |
| 2 | usage: a missing argument, an unknown flag or command |

## JSON output

With `--format json` (or `--json`) every line is one JSON object. `v` is the format's version; `mocked` marks numbers from the mock.

```sh
$ vakna ls --format json | jq -r .name
```

```prints
api
worker
web
docs
prove-hypothesis-42-0137
prove-hypothesis-42-0588
prove-hypothesis-42-0412
```

## Errors

- [`vakna: unknown command, unknown flag or missing argument`](https://vakna.com/docs/errors/usage): Run `vakna <command> --help` and fix the command line it points to.

## --help

This page and the help text come from one definition.

```prints
vakna list · list boxes

usage
  vakna list

aliases
  ls

flags
  -q, --quiet        names only  (default: off)
  --format <format>  text, or json: one JSON object per line  (default: text)
  --json             the same as --format json  (default: off)
  -h, --help         this help  (default: off)

examples
  vakna list
  vakna ls --format json | jq -r .name

exit codes
  0  ok
  1  vakna failed; under shell, run, try or fork, the command in the box failed
  2  usage: a missing argument, an unknown flag or command
```