Install the OnTrack CLI

ontrack needs Node.js 22.5 or later, or a recent Bun. It ships as a single binary named ontrack.

Install

npm install -g ontrack

bun add -g ontrack

bunx --bun ontrack --version

Point it at your site

Set the OnTrack site’s root URL, either as an environment variable or in the config file:

export ONTRACK_BASE_URL="https://ontrack.example.edu"

base_url: https://ontrack.example.edu

The URL must be the site’s root: no path, query string or credentials. See Configuration for the full key and file-path rules.

First run

Run any command at a terminal without ONTRACK_BASE_URL set and neither in the config file, and ontrack asks for the site once and saves it:

$ ontrack units
? OnTrack URL: https://ontrack.example.edu

If it then finds no usable session, it offers to open your browser and sign in:

No active OnTrack browser session was found. Run `ontrack auth login` to sign in.
Sign in once in your browser; later commands reuse that session.
? Sign in through the browser now? (Y/n)

This prompt only appears at an interactive terminal. A script or agent shell gets the underlying error instead — see Sign in for what each path does, and Errors and exit codes for how failures surface in --json.

​Install

​Point it at your site

​First run

Install

Point it at your site

First run