Command reference

Every chartnaut command and flag, as the CLI defines them. chartnaut <command> --help prints the same list in your terminal, and the source for each command is in chartnaut/cli on GitHub.

$ chartnaut run --help
Usage: chartnaut run [options] <target>

run a local script folder/file (inline) or a saved ref on Chartnaut servers

Arguments:
  target              path to a script folder or file, or a ref (slug, slug@3,
                      author/slug, chartnaut/rsi)

Options:
  --on <instruments>  instrument, or comma list (one run each, max 3 at once)
  --tf <timeframe>    timeframe (1m 5m 15m 30m 1h 2h 4h 1d 1w)
  --from <date>       window start (ISO date/time)
  --to <date>         window end (ISO date/time, default now)
  --last <span>       window as a span back from now, e.g. 30d, 12w, 6m, 1y
  --bars <n>          window as a bar count
  --set <key=value>   setting override (repeatable) (default: [])
  --kind <kind>       kind for a lone file outside a script folder
  --label <text>      free-text label shown in the app
  --wait              wait for the run to finish (default) (default: true)
  --no-wait           print the run id and exit
  --out <file>        write full results to file.csv or file.json
  -h, --help          display help for command

Options on every command

Every command exits with a fixed code from 0 to 5, so a script or a coding agent can branch on it. The codes are on Errors and exit codes.

Instruments, timeframes and windows

The commands that run something (run and collect) share these rules.

Pass exactly one of --last, --bars or --from. When you leave a flag out, the CLI takes it from defaults in the nearest chartnaut.json, which chartnaut init writes. A window ends on the last closed bar. A run window also starts no earlier than your plan's historical data reaches, and holds at most 50,000 bars.

A saved script is named by a ref: orb-break for your latest version, orb-break@3 for version 3, author/slug for someone else's script, and chartnaut/rsi for a built-in. chartnaut library search finds them.

Projects and scripts

chartnaut init

Sets up the current folder as a project: chartnaut.json, the indicators/, definitions/ and studies/ folders, and the agent guide in CLAUDE.md and AGENTS.md. It never removes or overwrites what you wrote. Running it again refreshes only the marked Chartnaut section of the guide. What it writes is on Working with Claude Code and Codex.

A default already in chartnaut.json is kept unless you pass its flag.

chartnaut new <kind> <slug>

Writes a starter folder, <kind-plural>/<slug>/, with script.json and main.ts. <kind> is indicator, definition or study. The slug is 2 to 63 characters of lowercase letters, digits and dashes, starting with a letter or digit.

chartnaut validate [path]

Lints and resolves a script without saving or running it. Free. path is a script folder or file and defaults to .. Prints ok: <slug> (<kind>) and the script's settings, outputs, events and dependencies, or one path:line: severity: message line per problem and exit code 1.

chartnaut push [path]

Saves a script folder as a new version, creating the script on its first push. path defaults to .. See Saving and versions.

chartnaut pull <ref>

Writes a saved version of your own script to local files. <ref> is slug or slug@N.

chartnaut diff <slug>

Prints a unified diff of your local files against the latest saved version. Takes a slug or a path to a script folder. Tells you when your folder is based on an older version than the latest.

chartnaut ls

Lists your scripts: slug, kind, version, visibility, last update and name.

chartnaut versions <slug>

Lists a script's versions, newest first, with when each was saved, who saved it and its change summary. Takes --limit and --cursor like ls.

chartnaut open <target>

Prints the app link for a script slug or a study run id. Indicator and definition runs have no page in the app.

Running

chartnaut run <target>

Runs a script on Chartnaut's servers and prints the summary. A path to a folder or file runs your local files and saves nothing. Anything else is a ref and runs the saved version. A study runs by ref only, so push it first. See Runs and results.

chartnaut runs

Lists your recent runs, newest first.

chartnaut runs get <id>

Prints a run's status, progress, failure, summary and console lines.

chartnaut runs results <id>

Prints what a finished run produced: series, events or study blocks.

chartnaut runs cancel <id>

Cancels a queued or running run and prints its new status.

A definition's events

See Definition events. Both commands work on your own definitions only.

chartnaut events <definition>

Lists the events your definition has from running over history, on every instrument and timeframe, from the app or the CLI.

chartnaut collect <definition>

Runs your definition over history on one instrument, timeframe and window, and keeps its events. Only the part of the window it has not covered yet runs.

--version <n> on events keeps the events that version found; on collect it runs that version. The same filter is version in the API.

Account and discovery

chartnaut login

Signs in through your browser: it prints a code and opens the approval page. See Sign in.

chartnaut logout

Signs out and revokes the key this machine used.

chartnaut whoami

Prints your user, plan, the key's name, expiry and scopes, and the API address.

chartnaut usage

Prints this period's compute and every plan cap with how much of it you use. --json adds the request limits. See Limits.

chartnaut instruments [q]

Lists the instruments you can run on, with their category, order flow and the dates they cover. q matches the symbol, the short symbol and the name.

chartnaut library search [q]

Searches every script you can use: your own, Chartnaut's built-ins, other people's public scripts and the ones you added to your library. Prints one row per script with its ref, kind, latest version, adoptions, author and name. Every word of q must appear in the name, slug, description, tags, category or author. The source never comes back. See Search the library.

The ref in the first column runs as it is: chartnaut run chartnaut/rsi --on BTC --tf 1h --last 30d.

chartnaut library show <ref>

Prints one library script: its ref, kind, version and author, its name and description, tables of its settings, outputs, events and results, and its app link. Never its source. The ref is author/slug, chartnaut/slug for a built-in or me/slug for your own, with @N for version N: chartnaut library show chartnaut/rsi. See Get a library script.

chartnaut docs [topic]

With no topic, lists the scripting reference topics. With one, such as chartnaut docs series-outputs, prints that topic as markdown. These are the Scripting pages.

chartnaut upgrade

Updates the CLI to the latest release. See Install.

Environment variables

chartnaut login saves your key in ~/.config/chartnaut/credentials.json, readable only by you.