Linear CLI troubleshooting

Fix the problem without guessing at commands.

Select the problem you are seeing, follow the checks in order and run only the command shown for that step. LinearCli.com never receives your API key, workspace information or terminal output.

Check in this order

01 CLI installed
02 Authentication
03 Project configuration
04 Issue connection

What problem are you facing?

ESC

Filter solutions

Real solutions

Choose the symptom you recognize

Open one solution at a time. Each answer explains the likely cause, the safest fix and how to confirm that it worked.

Likely cause

Linear CLI is not installed, or its executable directory is not available in your terminal’s PATH.

Fix it in this order

Close and reopen your terminal after completing installation.
Check whether the command is now available.
If it is still unavailable, return to the installation guide and use the method for your environment.

Check the installation This should display a version

linear --version

Working result: a Linear CLI version number appears in the terminal.

Open Installation Guide

Likely cause

The personal API key may be incomplete, expired, revoked or connected to a different Linear workspace. Guest accounts cannot create personal API keys.

Fix it in this order

Confirm that you are using a personal API key from the correct workspace.
Run the authentication command again.
Paste the key only into your local terminal prompt.

Authenticate again Runs locally in your terminal

linear auth login

Working result: the CLI accepts the key and can access your permitted Linear workspace.

Open Authentication Guide

Likely cause

The current repository has not been configured, the wrong workspace or team was selected, or an environment variable is overriding the project configuration.

Fix it in this order

Move into the correct project repository.
Run the configuration command.
Select the workspace, team and version control system used by that project.

Configure the current project Run from the repository folder

linear config

Working result: the project contains a usable Linear CLI configuration and commands use the intended team.

Open Configuration Guide

Likely cause

A Git branch does not contain a Linear issue identifier such as ENG-123, or a Jujutsu commit does not contain a Linear-issue trailer.

Fix it in this order

Confirm that the issue identifier is correct.
Start the issue through Linear CLI to create the required connection.
Check the detected issue identifier.

Connect the issue Replace ENG-123 with your issue

linear issue start ENG-123

Check the detected issue ID Reads the current work context

linear issue id

Working result: the terminal prints the connected issue ID, such as ENG-123.

Open Workflow Guide

Likely cause

The issues may belong to another workspace or team, may not be assigned to your account, or your API key may not have permission to read them.

Fix it in this order

Confirm that the expected issues are assigned to your Linear account.
Check that the project uses the correct workspace and team.
List the issues again after updating configuration.

List accessible issues Uses the configured workspace

linear issue list

Working result: issues available to the authenticated account appear in the terminal.

Likely cause

GitHub CLI may not be installed or authenticated, the repository may not have a GitHub remote, or the current issue cannot be detected.

Fix it in this order

Confirm that GitHub CLI is authenticated.
Confirm that the current branch contains the Linear issue ID.
Run the pull-request command again from the correct repository.

Check GitHub CLI authentication Confirms the active GitHub account

gh auth status

Retry the pull request Uses the current Linear issue

linear issue pr

Working result: the pull-request flow opens with issue information prepared through GitHub CLI.

Open GitHub CLI Integration

Final diagnostic

Run these checks before changing your setup

If all four checks work, the basic Linear CLI environment is ready and the problem is likely limited to one command or workflow.

Installation linear --version
Authentication linear issue list
Configuration linear config
Current issue linear issue id

Continue with the reference

Still unsure which command to use?

Browse the command reference by task and copy the exact command required for your workflow.

Browse Commands View Workflows

Fix the problem without guessing at commands.

CMD Installation The terminal says the Linear command cannot be found

Fix it in this order

KEY Authentication The API key is rejected or authentication fails

Fix it in this order

CFG Configuration Linear CLI cannot find the workspace or team

Fix it in this order

ID Issues & Git Linear CLI cannot detect the current issue

Fix it in this order

LIST Issues The issue list is empty or expected work is missing

Fix it in this order

PR GitHub CLI Linear CLI cannot create the pull request

Fix it in this order

No matching solution was found

Run these checks before changing your setup

Still unsure which command to use?