Kolo CLI¶
kolo¶
kolo [OPTIONS] COMMAND [ARGS]...
Options
- -v, -V, --version¶
Show the version and exit.
trace¶
Subcommands for working with Kolo traces.
kolo trace [OPTIONS] COMMAND [ARGS]...
compact¶
Get a compact representation of a specific trace.
[LEGACY] This command is deprecated. Use kolo cat instead.
Get a concise yet detailed overview of everything that happened in the trace. You will see a tree representation of all function calls (and optionally return values), as well as other relevant information and points of interest in the trace like logs or sql queries.
When called without arguments, shows the most recent trace.
kolo trace compact [OPTIONS] [TRACE_ID]
Options
- --pinned¶
Show compact representation of all pinned traces
- --returns¶
Include return values in compact representation (warning: can be verbose)
- --recent <recent>¶
Show compact representation of the N most recent traces (default: 5)
Arguments
- TRACE_ID¶
Optional argument
delete¶
Delete one or more traces stored by Kolo.
kolo trace delete [OPTIONS] [TRACE_IDS]...
Options
- --old¶
Delete old traces. Defaults to traces older than 30 days.
- --before <before>¶
Delete traces older than this datetime. Must be used with –old.
- --vacuum¶
Recover disk space from the Kolo database.
Arguments
- TRACE_IDS¶
Optional argument(s)
download¶
Download a trace from the Kolo dashboard
kolo trace download [OPTIONS] TRACE_ID
Arguments
- TRACE_ID¶
Required argument
emit¶
Emit a trace into a browsable directory structure.
When called without arguments, emits/updates the 5 most recent traces.
Creates a directory tree that mirrors the trace’s execution tree, with human-readable files for each node (.py for syntax highlighting, .sql for SQL). This makes it easy to:
The output includes: | - {trace_id}.txt: Trace metadata and compact tree (overview) | - Nested directories mirroring execution flow | - call.py/return.py for function calls with locals (Python syntax highlighting) | - request.txt/response.txt for HTTP (plain text) | - .sql for SQL queries
kolo trace emit [OPTIONS] [TRACE_ID]
Options
- -o, --output-dir <output_dir>¶
Directory where the trace directory will be created. Defaults to .kolo/traces/
Arguments
- TRACE_ID¶
Optional argument
json-to-msgpack¶
Convert all legacy json traces to msgpack
kolo trace json-to-msgpack [OPTIONS]
list¶
Concisely list available traces, ordered by most recent first.
This is useful for getting an overview of what traces are available and finding specific traces you might want to analyze further.
Use kolo cat <trace_id> to view a trace or kolo cat –recent to view recent traces.
If you’re an LLM, use kolo trace list often to orient yourself.
kolo trace list [OPTIONS]
Options
- --count <count>¶
The number of rows to show.
- --reverse¶
Reverse the order of the rows: newest at the bottom.
- --pinned¶
Show only pinned traces.
node¶
Get detailed information about a specific node in a trace. This is useful when you need to deeply understand what happened at a specific point in the execution, like examining function arguments, local variables, or the exact line of code being executed.
kolo trace node [OPTIONS] TRACE_ID NODE_INDEX
Arguments
- TRACE_ID¶
Required argument
- NODE_INDEX¶
Required argument
pin¶
Pin a trace. This includes the trace in the output of using kolo cat –pinned, which can be helpful to give an LLM an overview of the key transactions in your project.
kolo trace pin [OPTIONS] TRACE_ID
Arguments
- TRACE_ID¶
Required argument
unpin¶
Unpin a previously pinned trace.
kolo trace unpin [OPTIONS] TRACE_ID
Arguments
- TRACE_ID¶
Required argument
upload¶
Upload a trace to the Kolo dashboard
kolo trace upload [OPTIONS] TRACE_ID
Arguments
- TRACE_ID¶
Required argument
run¶
Trace Python code using Kolo.
PATH is the path to the python file or module being traced.
kolo run [OPTIONS] PATH [ARGS]...
Options
- --one-trace-per-test¶
Generate a trace for each test traced by Kolo.
- --inline¶
Output the compact tree representation of the trace to stderr after execution.
- --returns¶
Include return values in the compact tree representation.
Arguments
- PATH¶
Required argument
- ARGS¶
Optional argument(s)
server¶
Start a server to view traces.
kolo server [OPTIONS]
Options
- --port <port>¶
Custom port for the server to run on. Defaults to 5656.
- --ip <ip>¶
Custom ip for the server to run on. Defaults to 127.0.0.1
cat¶
Get a compact, text-based representation of a trace.
Shows a concise yet detailed overview of everything that happened in the trace. You will see a tree representation of all function calls (and optionally return values), as well as other relevant information and points of interest in the trace like logs or sql queries.
This is the canonical command for viewing compact trace representations.
When called without arguments, shows the most recent trace.
kolo cat [OPTIONS] [TRACE_ID]
Options
- --pinned¶
Show compact representation of all pinned traces
- --returns¶
Include return values in compact representation (warning: can be verbose)
- --recent <recent>¶
Show compact representation of the N most recent traces (default: 5)
Arguments
- TRACE_ID¶
Optional argument