CLI

Configuration

Where the CLI reads settings from, which environment variables it honors, and how to control telemetry.

The CLI reads each setting from flags, environment variables, its config file and built-in defaults, and stores everything under ~/.polylane. This page lists the order, the variables and how to control telemetry.

Precedence

The CLI resolves each setting in this order, highest wins:

CLI flags, for example --workspace, --api-key, --output and --timeout.
Environment variables: the POLYLANE_* set plus the standard NO_COLOR and DO_NOT_TRACK.
For the credential only, OAuth tokens in ~/.polylane/credentials.json.
The config file at ~/.polylane/config.json.
Built-in defaults: domain api.polylane.com, timeout 300 seconds, output text in a terminal and json when piped.

An exported POLYLANE_API_KEY always beats a stale ~/.polylane/credentials.json, so a CI runner with the variable set does not pick up leftover OAuth tokens. Authentication lists the same order for credentials.

Config file

~/.polylane/config.json accepts six keys: domain, workspace_id, api_key, output, timeout and telemetry. Manage it through the CLI: config show prints the resolved configuration, the auth method in use and the file path, with API keys masked.

Terminal

polylane config show
polylane config set --key output --value json

To set the default workspace by slug instead of id, run polylane workspace use <slug>. OAuth credentials live separately in ~/.polylane/credentials.json and refresh on their own when the access token nears expiry.

Environment variables

Variable	Description
`POLYLANE_API_KEY`	Authenticate without storing a key on disk
`POLYLANE_WORKSPACE_ID`	Set the workspace for the current shell
`POLYLANE_API_DOMAIN`	Point at a different API hostname; hostname only, no protocol
`POLYLANE_OUTPUT`	Force `text` or `json` output
`POLYLANE_TIMEOUT`	Request timeout in seconds
`POLYLANE_VERBOSE`	Enable verbose logging
`POLYLANE_TELEMETRY=0`	Disable telemetry for this environment
`DO_NOT_TRACK=1`	The universal telemetry opt-out; overrides every other telemetry setting, including the config file
`NO_COLOR`	Disable ANSI colors

Telemetry

Anonymous usage telemetry is on by default. It records the command name, flag names, the count of positional arguments, the exit code and error category, durations, CLI and Node versions, operating system details, an anonymous per-install identifier and the workspace id. Flag values, arguments, file paths, command output and full error messages stay out of it, and polylane telemetry status shows exactly what is sent and where.

Turn it off for good with polylane telemetry disable, which writes to the config file, or per environment with POLYLANE_TELEMETRY=0 or DO_NOT_TRACK=1. The decision follows DO_NOT_TRACK, then POLYLANE_TELEMETRY, then the config file, then the default of on; there is no per-invocation flag.

Files on disk

Everything the CLI stores lives under ~/.polylane:

File	Description
`config.json`	Saved settings: domain, workspace, API key, output, timeout, telemetry
`credentials.json`	OAuth tokens
`telemetry.json`	Anonymous install id and run counters
`update-state.json`	Update check state

Delete the directory to reset the CLI completely; a fresh install id is generated on the next run.

Authentication: the sign-in methods and how credentials are chosen.
Scripting: the output contract, script flags and exit codes.

Scripting

Drive the CLI from shell scripts, CI and coding agents with JSON output, stable exit codes and no prompts.

Plugins