Skip to main content

Configuration reference

Credential precedence​

For API requests, the exact precedence is:

  1. --api-key <key> on the current invocation.
  2. LINEAR_API_KEY in the environment.
  3. api_key in ~/.config/linear-cli/config.yaml.

The flag is selected explicitly in cmd/root.go; Viper's environment binding makes LINEAR_API_KEY override the file value. A missing key returns AUTH_ERROR with exit code 3.

File and keys​

The config directory is ~/.config/linear-cli, and the file is config.yaml. auth login and config set create the directory with mode 0700 and write the file.

KeyValueEffect
api_keyLinear API keyUsed as the lowest-precedence API credential. auth login --token writes this key.
default_teamTeam key such as ENGSupplies the team for issue list and issue create when --team is absent.

Use the config commands:

linear-cli auth login --token lin_api_example
linear-cli config set default_team ENG
linear-cli config get default_team
linear-cli config list

config set <key> <value> accepts the two positional arguments for any key, but the CLI's documented operational keys are api_key and default_team. config list redacts api_key: values longer than eight characters retain their first eight characters followed by ***; shorter non-empty values become ***.

For automation, prefer LINEAR_API_KEY over --api-key or putting a token in shell history. Never paste a real token into documentation, logs, issue descriptions, or an agent transcript.