This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent works in a shell, it can use the unofficial linear CLI to read Linear issues while it examines code. The CLI also reads workspace data beyond issues, including teams, projects, and milestones. It can also retrieve documents and comments, giving the agent context to investigate an issue before proposing code changes.
The CLI is a community project. It lives in the personal GitHub account of its author, Peter Schilling (schpet), outside Linear's own organization. Its commands for listing and viewing issues suit read-only tasks. The agent sends requests to Linear to retrieve workspace data. linear --help shows usage information from the local CLI.
Install and authenticate
The project's README documents several installation methods. With Homebrew, install it from the author's tap:
brew install schpet/tap/linear
The README also covers an npm package (@schpet/linear-cli) and a shell installer, among other methods. After installing, run linear --help to see the commands and options in your installed version.
The CLI authenticates with a Linear API key. Create the key in Linear's account security settings. The README notes that creating one requires member access, so guest accounts can't do it. Then store it with:
linear auth login
The command prompts for the key. According to the authentication docs, stored keys go into the system keyring, such as macOS Keychain or libsecret on Linux. The CLI also accepts a LINEAR_API_KEY environment variable. Do not put an API key or other secret in a task description. An agent with shell access can use any key the CLI can reach, and linear auth token prints the stored key, so keep that command out of agent tasks.
linear config sets up the CLI for a repository and writes a config file, which holds settings such as the default team. Before letting an agent make changes, check what the configured Linear account can change. The CLI uses the permissions attached to its credentials, so commands the agent runs have the access available to that account.
Read an issue from the shell
For a read-only task, ask the agent to inspect an issue and explain how it relates to the checked-out code. Replace ENG-123 with an issue identifier from your workspace.
linear issue list --json
linear issue view ENG-123 --json
linear issue list retrieves your issues. By default it shows unstarted issues assigned to you, up to 50 of them. linear issue view retrieves details for the specified issue, including its comments. Without an ID, it uses the issue named in the current git branch. The agent can compare the issue description with local files and report likely code locations or questions before editing. Both commands send requests to Linear, but neither changes workspace data.
The --json option prints structured output, which the agent can parse more reliably than a formatted table. The README also shows linear issue query for searching issues by text or filters, which supports --json too.
A realistic prompt for this example is:
Read issue ENG-123 with the Linear CLI using
linear issue view ENG-123 --json. Compare its description with the current checkout, identify the files that appear relevant, and report any uncertainty. Do not edit files or change the issue.
The prompt asks the agent to retrieve an issue from Linear, inspect local code, and report its findings. The agent contacts Linear to look up the issue and reads files locally. Because the prompt separates investigation from changes, the agent does not update the issue or edit code.
Check changes and sensitive attachments
The CLI can also create and update issues. linear issue start creates or switches to a git branch for the issue and marks it as started. These commands change workspace data. Ask the agent to show what it plans to do, then explicitly authorize the change. Check the installed command’s help for a preview or dry-run option before using a write command; do not assume one exists.
Take care when attaching files. According to the README, uploads are private to workspace members by default. With --public, the CLI uploads raster images to a public URL that anyone can read without signing in. This bypasses workspace access controls. The CLI prints a warning, and non-image files cannot be made public. Do not use --public for confidential images.
An agent can use linear issue list and linear issue view in a shell to get issue context while working in a codebase. Before relying on the CLI, check the repository’s current installation, authentication, and option instructions. Keep commands that change workspace data separate from read-only investigation.