authentication

April 2, 2026 · View on GitHub

the CLI supports multiple authentication methods with the following precedence:

--api-key flag (explicit key for single command)
LINEAR_API_KEY environment variable
api_key in project .linear.toml config
--workspace flag → stored credentials lookup
project's workspace config → stored credentials lookup
default workspace from stored credentials

stored credentials (recommended)

API keys are stored in your system's native keyring (macOS Keychain, Linux libsecret, Windows CredentialManager). workspace metadata is stored in ~/.config/linear/credentials.toml.

commands

linear auth login              # add a workspace (prompts for API key)
linear auth login --key <key>  # add with key directly (for scripts)
linear auth list               # list configured workspaces
linear auth default            # interactively set default workspace
linear auth default <slug>     # set default workspace directly
linear auth logout <slug>      # remove a workspace
linear auth logout <slug> -f   # remove without confirmation
linear auth whoami             # show current user and workspace
linear auth token              # print the resolved API key

adding workspaces

# first workspace becomes the default
$ linear auth login
Enter your Linear API key: ***
Logged in to workspace: Acme Corp (acme)
  User: Jane Developer <jane@acme.com>
  Set as default workspace

# add additional workspaces
$ linear auth login
Enter your Linear API key: ***
Logged in to workspace: Side Project (side-project)
  User: Jane Developer <jane@example.com>

switching workspaces

# set a new default
linear auth default side-project

# or use --workspace flag for a single command
linear --workspace side-project issue list
linear --workspace acme issue create --title "Bug fix"

credentials file format

# ~/.config/linear/credentials.toml
default = "acme"
workspaces = ["acme", "side-project"]

API keys are not stored in this file. they are stored in the system keyring and loaded at startup.

platform requirements

macOS: uses Keychain via /usr/bin/security (built-in)
Linux: requires secret-tool from libsecret
- Debian/Ubuntu: apt install libsecret-tools
- Arch: pacman -S libsecret
Windows: uses Credential Manager via advapi32.dll (built-in)

if the keyring is unavailable, set LINEAR_API_KEY as a fallback.

migrating from plaintext credentials

older versions stored API keys directly in the TOML file. if the CLI detects this format, it will continue to work but print a warning. run linear auth login for each workspace to migrate keys to the system keyring.

environment variable

for simpler setups or CI environments, you can use an environment variable:

# bash/zsh
export LINEAR_API_KEY="lin_api_..."

# fish
set -Ux LINEAR_API_KEY "lin_api_..."

this takes precedence over stored credentials. if you have LINEAR_API_KEY set and try to use linear auth login, you'll see a warning:

Warning: LINEAR_API_KEY environment variable is set.
It takes precedence over stored credentials.
Remove it from your shell config to use multi-workspace auth.

project config

you can also set the API key in a project's .linear.toml:

api_key = "lin_api_..."
workspace = "acme"
team_id = "ENG"

this is useful for project-specific credentials but less secure than stored credentials since it may be committed to version control.

workspace matching

when your project config has a workspace setting:

# .linear.toml
workspace = "acme"
team_id = "ENG"

the CLI will automatically use the stored credentials for that workspace, even if a different workspace is your default. this lets you work on multiple projects with different workspaces without constantly switching.

creating an API key

go to linear.app/settings/account/security
scroll to "Personal API keys"
click "Create key"
give it a label (e.g., "CLI")
copy the key (starts with lin_api_)

note: creating an API key requires member access; it is not available for guest accounts.