Troubleshooting

The command reports no API key

Check the environment and config without printing the token:

test -n "$LINEAR_API_KEY" && echo "LINEAR_API_KEY is set" || echo "LINEAR_API_KEY is not set"
linear-cli config list

Set the environment variable or run linear-cli auth login --token <key>. The missing-credential response is AUTH_ERROR with exit code 3.

Authentication or permission failure

401 responses and GraphQL AUTHENTICATION_ERROR values map to AUTH_ERROR / 3. 403 responses and GraphQL FORBIDDEN values map to PERMISSION_DENIED / 7. Confirm the key is valid and that the Linear user can access the requested workspace object.

A resource is not found

Verify the identifier form. Issues use TEAM-NUMBER such as ENG-123; teams use keys; users, states, projects, cycles, and documents use Linear IDs. A missing resource maps to NOT_FOUND / 4.

Rate limit or network failure

HTTP 429 maps to RATE_LIMITED / 5. Connection failures, response-read failures, and HTTP 5xx responses map to NETWORK_ERROR / 6. Retry rate-limited or transient network operations according to the caller's policy; the CLI does not implement a retry loop.

Inspect output safely

Use --pretty to read a response:

linear-cli --pretty team list --limit 5

Use linear-cli version to identify the binary. Redact Authorization values, API keys, private issue content, and uploaded-file contents before sharing diagnostics. config list is safe to inspect because it redacts the configured API key.

Configuration read failures are printed as a warning during startup. A malformed or unreadable config can therefore coexist with a later authentication error; check the config path and file permissions.