Setup CLI environment

Use this guide to prepare a workstation for the published Parix CLI. It covers the latest @parix/cli package. See the Parix CLI overview for the release these docs track.

Requirements

You need:

• Node.js 20 or newer
• npm for global installation
• a Parix account with access to an organization
• a browser for the OAuth login flow

Install the CLI

Install the CLI globally:

npm install -g @parix/cli@latest

Verify the command and version:

parix --version
parix --help

The top-level command groups are:

auth
api
database
tb

Sign in

The CLI targets production by default:

https://parix.io

Sign in with the browser OAuth flow:

parix auth login

The CLI stores the local session at:

~/.config/parix/session.json

That session includes the signed-in user, token, scopes, active organization, and the base URL used for later commands. Typical production usage needs no base URL override.

After login, confirm the session:

parix auth status

Status output includes the signed-in user, base URL, token expiry, scopes, active organization, member role, and session file path.

Continue with Authentication for session lifecycle and organization selection, then Database and TigerBeetle for day-to-day commands.

Base URL resolution

Most workstations only need the production default. Commands that call Parix can override the origin with:

--base-url <url>

or with the PARIX_BASE_URL environment variable. Use either only when you deliberately target a trusted non-default origin. Never send credentials or requests to an origin you do not trust.

API, database, TigerBeetle, and auth status resolve the target in this order:

1. --base-url
2. the base URL stored in ~/.config/parix/session.json
3. PARIX_BASE_URL
4. https://parix.io

Because a stored session wins over the environment variable, a one-shot --base-url changes the request origin for that command only. It does not obtain a new credential for that origin; the CLI still attaches the current stored bearer token. Authenticate to an origin before relying on it:

parix auth login --base-url <trusted-origin>

parix auth login intentionally ignores the base URL from an existing session so a stale session cannot silently pin a new login. Login resolves --base-url, then PARIX_BASE_URL, then https://parix.io.