Definition events

A definition's events are every event it found when it ran over history, on every instrument, timeframe and window, whether you ran it from the app or from the CLI. Studies read these events. chartnaut events reads and filters them, and chartnaut collect runs the definition over more history. Both work on your own definitions only. The API calls behind them are List events, Summarise events and Run a definition over history.

A chartnaut run of a definition is separate: it returns that run's events and stores nothing a study can read.

See what a definition has

$ chartnaut events bull-bar --summary
bull-bar: 25690 events over 90 days (285.44/day)
INSTRUMENT       TF  EVENTS  FROM              TO
HYPERLIQUID:BTC  5m  12910   2026-06-28 10:00  2026-09-26 10:00
HYPERLIQUID:ETH  5m  12780   2026-06-28 10:00  2026-09-26 10:00

The first line is the total across everything. Each row is one instrument and timeframe the definition has run over, with the span it covers. Two more lines appear when they apply: collecting: 1 window(s) still running, and failed: with the number of runs that failed and why. A definition with nothing yet prints the chartnaut collect command to start with.

Run it over more history

$ chartnaut collect bull-bar --on BTC --tf 5m --last 1y --wait
bull-bar@4 on HYPERLIQUID:BTC 5m: collecting 2 window(s)
65190 events collected in total

This runs the latest version of the definition over the window and stores its events, the same as running it over history in the app. Only the part of the window the definition has not covered yet runs. When all of it is covered, the command prints already collected and does nothing.

• --on, --tf and the window work as they do for run: --last, --bars or --from and --to. Command reference

• Without --wait, the command returns at once and prints check: chartnaut events bull-bar --summary.

• With --wait, it checks every 3 seconds, for up to 20 minutes, until nothing is running. It then prints the definition's total across every instrument, not only this window. If running this instrument and timeframe over history fails, it prints failed: with the reason and exits 2, or 5 when the failure is worth retrying or it is still running after 20 minutes.

• The events count toward your plan's definition events.

You rarely need collect before a study. A study run from the CLI runs each definition it declares over the study's window first, and only the missing part runs.

Read the events

$ chartnaut events bull-bar --on BTC --from 2026-09-01T00:00:00Z --limit 3
START             INSTRUMENT       TF  EVENT     PAYLOAD
2026-09-01 00:05  HYPERLIQUID:BTC  5m  bull_bar  {"range":184.5}
2026-09-01 00:10  HYPERLIQUID:BTC  5m  bull_bar  {"range":96.25}
2026-09-01 00:20  HYPERLIQUID:BTC  5m  bull_bar  {"range":132}
3584 total · more: --cursor 3 (or --all)

Events come back oldest first, 100 to a page by default and up to 1,000 with --limit. --all follows every page. CSV follows every page on its own unless you give --limit or --cursor.

--where takes a list of conditions on payload keys. The operators are eq, neq, contains, gt, gte, lt, lte, between, is_empty and is_not_empty.

--version <n> on events keeps the events one version of the definition found, and on collect runs that older version. chartnaut --version on its own still prints the CLI's version.

Save them to a file

--out events.csv writes CSV and --out events.json writes JSON, and --format csv prints CSV to the terminal. The CSV columns are event,intent,instrument,timeframe,start,end,bar_index,payload, with the payload as JSON. CSV holds every event under one header row. JSON holds every event with --all.

To browse the same events in the app, see Browse events.