CLI Configuration | FlightStack

Configuration

The CLI keeps everything in a single hidden directory in your home folder. No global system config, no XDG state — just one place to look.

Configuration directory

Platform	Location
macOS, Linux	`~/.flightstack/`
Windows	`%USERPROFILE%\.flightstack\`

Files

`config.json`

The CLI’s main configuration — written by flightstack login and managed by flightstack config.

{
  "apiUrl": "https://api.flightstack.voostack.com",
  "accessToken": "eyJhbG...",
  "refreshToken": "eyJhbG...",
  "tokenExpiresAt": "2026-06-15T01:42:00Z",
  "userId": "7d2a8c84-...",
  "email": "you@example.com",
  "autoUpdate": true,
  "lastUpdateCheck": "2026-06-14T12:00:00Z"
}

Field	Description
`apiUrl`	Control-plane base URL. Self-hosted users set this to their domain.
`accessToken`	Current OAuth access token.
`refreshToken`	Used to refresh `accessToken` automatically when it expires.
`tokenExpiresAt`	ISO-8601 timestamp when `accessToken` expires.
`userId`, `email`	Identifies the signed-in user. Convenient for `flightstack config`.
`autoUpdate`	When `true`, the CLI checks for updates daily and self-installs.
`lastUpdateCheck`	Used to throttle the update check.

Agent `config.json`

If this machine is also registered as a build agent, the agent writes its own config:

{
  "agentId": "a1b2c3d4-…",
  "token": "eyJhbG...",
  "apiUrl": "https://api.flightstack.voostack.com",
  "agentName": "macbook-pro",
  "platform": "macOS",
  "organizationId": null,
  "organizationName": null
}

Written by flightstack agent register. The token here is the agent token — distinct from your user accessToken. It’s used in the Agent-Token HTTP header (see API authentication).

`agent.log` and `agent.pid`

agent.log — runtime logs when the agent runs in daemon mode (rotates at ~10 MB).
agent.pid — process ID of the running agent. Used by flightstack agent stop and status.

Environment variables

Variable	Description
`FLIGHTSTACK_API_URL`	Override the API URL for this process only.
`FLIGHTSTACK_TOKEN`	Override the access token for this process only.

Both are read at startup and take precedence over config.json. Useful in CI scripts where you want to inject credentials without writing them to disk.

FLIGHTSTACK_API_URL=https://flightstack.acme.internal \
FLIGHTSTACK_TOKEN=eyJhbG... \
flightstack repo --list

Switching backends (self-hosted vs cloud)

The supported way is flightstack config --api-url <url>:

# Move to self-hosted
flightstack config --api-url https://flightstack.acme.internal
flightstack login --force

# Move back to cloud
flightstack config --api-url https://api.flightstack.voostack.com
flightstack login --force

You can also edit config.json directly, but you’ll need to re-authenticate either way — tokens are tied to the API URL they were issued against.

Resetting

Wipe everything (config, tokens, agent registration):

flightstack config --reset
# or, manually:
rm -rf ~/.flightstack

Then run flightstack login again.

Custom API URL for self-hosted

See Self-hosting → options for picking a deployment model, and Self-hosting → configuration for what URL to point the CLI at.