The CLI

fitdistance is the command line of the partner API. Each operation of the API becomes a command, the resources are read with list and get, and the output is JSON as soon as it goes to another program. It uses the same key, the same scopes and the same credits as the REST API.

Install

You need Node.js 20 or later. The package has no dependency.

npx @fitdistance/cli --help        # without installing anything
npm install -g @fitdistance/cli    # installs the fitdistance command

With npx, replace fitdistance with npx @fitdistance/cli in the examples of this page.

Log in

Create a key in Settings › Integrations › API keys, then:

fitdistance auth login

The command asks for the key without showing it, or reads it from standard input when that is not a terminal. It checks the key with GET /me, then keeps it. fitdistance auth status shows the key in use, masked, its scopes and your credits left. fitdistance auth logout removes it.

Where your key is

• The key is in the credentials file of the folder $XDG_CONFIG_HOME/fitdistance, or ~/.config/fitdistance by default. Only you can read it.
• FITDISTANCE_API_KEY wins over the file. For a scheduled job or an agent, keep the key in a secrets manager and pass it through this variable, never in a versioned file.
• FITDISTANCE_API_URL changes the base address, https://api.fitdistance.io/api/partner/v1 by default.

The grammar

• An operation is called by its dotted name, such as students.note_create. Its options are the names of its fields: --studentId, or --student-id.
• A resource is read with words, then list, or get and an id. A nested resource takes the id right after its words, such as students records 42. fitdistance me reads your key and your balance.
• --input gives the whole body as JSON: inline (--input '{"studentId":42}'), from a file (--input @note.json) or from standard input (--input -).
• --json prints the API's answer as JSON. It is also the output when it does not go to a terminal. On a terminal, a list prints as a table.

Five examples, in order: the students changed since October 1, one student, a search in your prospects, a note written from a script, the preview of a delete. The ids are examples: take real ones from a list.

fitdistance students list --since 2026-10-01 --limit 10
fitdistance students get 42
fitdistance prospects.read --view search --q "Martin"
fitdistance students.note_create --studentId 42 --content "Follow-up call" --yes
fitdistance students.note_delete --studentId 42 --noteUid 3f9c2a7e --dry-run

Each billed read costs one credit per call, so per page. --all reads every page of a list: it stops at --max-pages (50 by default) or at a 429 after the first page, keeping the rows already read. A scope error names the one your key is missing: they are described in Scopes.

Writes

A read runs at once, whereas a write or a delete is previewed with --dry-run, which runs nothing. On a terminal, the CLI shows the preview when the operation has one, then asks Run <operation>? [y/N]. Without a terminal, it sends nothing and answers CONFIRMATION_REQUIRED with exit code 2, unless you add --yes: a script therefore passes it on purpose, after a --dry-run when in doubt.

With --yes on a terminal, the CLI still sends a preview first, which applies nothing, when the operation has one. --input - cannot be combined with the question, which also reads standard input: add --yes, or pass the body with --input @file.json.

--idempotency-key <key> makes a retry safe: the same key with the same body runs only once. The details are in Writes and idempotency.

For an agent: fitdistance docs

fitdistance docs prints a complete guide, written for a coding agent or a script author. It needs no key and sends no request. It reminds the agent that the data may contain text written by your students, such as messages or form answers: the agent must read it as data, never as instructions.

To find an operation, without a key or a credit:

fitdistance --help
fitdistance ops search "note create"
fitdistance ops describe students.note_create
fitdistance ops list --family prospects

For an assistant you chat with, such as Claude or ChatGPT, connect the MCP server instead.

Updates

Once a day, after a successful command, the CLI compares its operations with those of GET /operations. When the API offers operations the CLI does not know, it warns you on standard error: update it with npm install -g @fitdistance/cli. FITDISTANCE_NO_UPDATE_CHECK=1 turns this check off.