# Kolo CLI

Run `kolo` with no arguments to see the available commands, your five most recent traces and the path to `.kolo/kolo.txt`.

To read a trace, start with [`kolo cat`](#kolo-cat). To capture one, use [`kolo run`](#kolo-run), [`kolo attach`](#kolo-attach) or one of the [other ways to capture a trace](../howto/trace-function-or-script.md).

```{eval-rst}
.. click:: kolo.__main__:cat
   :prog: kolo cat
```

```{eval-rst}
.. click:: kolo.__main__:trace
   :prog: kolo trace
   :nested: full
   :commands: list, node, emit, delete, pin, unpin, upload, download
```

```{eval-rst}
.. click:: kolo.__main__:run
   :prog: kolo run
```

```{eval-rst}
.. click:: kolo.__main__:attach
   :prog: kolo attach
```

```{eval-rst}
.. click:: kolo.__main__:server
   :prog: kolo server
```

## Legacy commands

These commands still work, but you should not need them.

- `kolo trace compact`: deprecated alias of [`kolo cat`](#kolo-cat).
- `kolo trace json-to-msgpack`: one-off migration for traces stored in the JSON format that old versions of Kolo used.

## Hidden commands

These commands are left out of `kolo --help`. Most are for debugging Kolo itself.

- `kolo trace flat [TRACE_ID]`: print a trace as a single markdown document instead of a directory of files. Useful for diffing two traces or sharing one. Without a trace ID it prints the most recent trace.
- `kolo trace dump TRACE_ID`: write a trace's raw binary data to stdout, or to a file with `--file`. Pass `--as-python` to print it as readable Python objects instead.
- `kolo mcp`: start Kolo's [MCP server](../howto/mcp.md). Agents with a shell do better running the CLI and grepping `.kolo/traces/` directly, which is what the [Kolo skill](../howto/skill.md) teaches.
- `kolo migrate`: move trace data from the SQLite database used before v3 to file-based storage. Kolo runs this automatically when needed. `--status` shows progress without migrating.
- `kolo dbshell`: open a `sqlite3` shell on Kolo's metadata database.
- `kolo ci upload`: upload all local traces to Kolo's dashboard. Needs the `KOLO_TOKEN` environment variable.