Saving and versions

chartnaut push saves a script folder as a new version in Chartnaut, and chartnaut pull writes a saved version back to disk. Between them, script.json remembers which version your folder is based on, so a push never lands silently on top of a change made in the app.

Running a folder with chartnaut run saves nothing. Push when you want the script in the app, on a chart, or in a study.

What a version is

Each push adds a version: orb-break@1, orb-break@2 and so on. A version the CLI has saved or run never changes afterwards, so orb-break@3 is the same code a year from now. Runs record the version they used, and a bare orb-break means the latest. How versions work in the app is on Versions and profiles.

script.json holds the version your folder was last pushed or pulled at:

{
  "kind": "definition",
  "slug": "orb-break",
  "name": "Opening range break",
  "entry": "main.ts",
  "version": 3
}

Leave version alone. The CLI updates it on every push and pull. It is the base_version a push sends to Save a script version.

Push

$ chartnaut push definitions/orb-break -m "wait for a close outside the range"
pushed orb-break@4
app: https://terminal.chartnaut.com/morpheus/flow-builder-v2/412

The first push of a folder with no version creates the script, private unless you pass --visibility public. Every later push sends the folder's version and saves the next one.

A push is checked the same way chartnaut validate checks. If anything fails, nothing is saved: you get the path:line: lines and exit code 1.

A push sends every file in the folder except script.json, dotfiles and node_modules, and a file you deleted locally is gone from the new version too. Files must be .ts or .js. An indicator is a single file. A definition or a study can have up to 50 files, each up to 512 KB and 2 MB together.

When someone saved first

If the script has a newer version than your folder, because someone saved it in the app or pushed from another machine, the push stops with exit code 4:

$ chartnaut push definitions/orb-break -m "tighter range"
error: version_conflict: orb-break is at version 5, not 4. Pull it, re-apply your change, and save again.. Run `chartnaut pull orb-break` to get it, or push --force to save on top of it.

To keep both changes:

1. Run chartnaut diff orb-break to see how your files differ from the latest version.

2. Copy your changed files somewhere safe, because chartnaut pull orb-break overwrites them with version 5.

3. Re-apply your change on top of version 5.

4. Run chartnaut push definitions/orb-break -m "tighter range".

--force skips all that and saves your files as the next version on top of the latest. Version 5 is still there as orb-break@5, but the latest version no longer has its changes. Use it when you know the app's change should go.

A first push also stops, with a conflict error, when you already have a script of that type with that slug. --force then saves your folder as the next version of that script.

Pull

$ chartnaut pull orb-break
pulled orb-break@5 → definitions/orb-break (2 files)

pull writes into the script's existing folder, or <kind-plural>/<slug> if there is none, and sets version in script.json. --dir picks another folder. You can pull your own scripts only.

If your folder has files the version does not, pull leaves them and prints a warning naming them. The next push sends them, so delete the ones you do not want.

Go back to an older version

1. Run chartnaut versions orb-break to find the version you want.

2. Run chartnaut pull orb-break@2.

3. Run chartnaut push definitions/orb-break --force -m "back to v2".

The push conflicts because your folder is now based on version 2, and --force saves version 2's code as the newest version.

Version history

$ chartnaut versions orb-break
VERSION  CREATED           AUTHOR  SUMMARY
5        2026-09-26 08:40  you     Added a minimum range
4        2026-09-25 17:02  api     wait for a close outside the range
3        2026-09-25 16:15  api     first push

The author is api for a push from the CLI or the API and you for a save in the app. A save by the app's agent shows the model's name, or app-agent. List versions returns the same from the API.

The CLI does not delete scripts. Delete them in the app or through the API.