phnx-labs/linear-cli

linear-cli

Linear for you and your agents. Same queue, same CLI.

Linear for human-owned work and agent-executed handoff. Keep the human as assignee, delegate the issue to an agent with --delegate, and require proof before --done closes the loop.

Use the same shell contract whether you're typing or a subagent is: query the queue, delegate the work, ship progress notes, and close only with evidence. Single-file Python (stdlib only) keeps install and audit overhead low, but the moat is the delegation workflow.

<p align="center" <img src="assets/flow.svg" alt="How a Linear ticket becomes a PR: a human files the ticket and stays the assignee, an agent becomes the delegate, ships a PR plus proof, then the human reviews. linear-cli is the contract between them." width="100%" / </p

<p align="center" <a href="https://github.com/phnx-labs/linear-cli/releases/download/v0.1.0/LinearDemo.mp4" <img src="https://github.com/phnx-labs/linear-cli/releases/download/v0.1.0/LinearDemo.gif" alt="linear-cli in 30 seconds: list your queue, claim a ticket with --pickup, close it with --done --proof. Click through for the MP4 with audio." width="100%" / </a <br / <sub<a href="https://github.com/phnx-labs/linear-cli/releases/download/v0.1.0/LinearDemo.mp4"Watch with audio (MP4, 1.4 MB)</a</sub </p

Install

Preferred (pinned tag + SHA-256 verify via install.sh):

curl -sSL https://raw.githubusercontent.com/phnx-labs/linear-cli/v0.24.2/install.sh | sh

Manual pin (same tag; no checksum — prefer install.sh above):

curl -o ~/.local/bin/linear https://raw.githubusercontent.com/phnx-labs/linear-cli/v0.24.2/linear
chmod +x ~/.local/bin/linear

Setup

Create a Linear API key with Full access at linear.app/settings/account/security, then:

linear setup --api-key lin_api_... --agent claude

Config is written to ~/.linear-cli/config.json. If you already have ~/.agents/linear.json from an earlier setup, linear-cli auto-migrates it on first run.

Security: treat the API key like a password. Do not paste it into chat with an LLM in plaintext. Pass it from your shell env (linear setup --api-key "$LINEARAPIKEY"), or let linear-cli read it from the macOS Keychain. Resolution order is: config file → LINEARAPIKEY env → Keychain service linear-api-key.

Fleet setup for agents

For a shared agent fleet, mint the Full-access key once with agents browser so the browser session drives linear.app/settings/account/security instead of exposing the key in chat. Store it in agents secrets / the OS keychain, then let each session run with LINEARAPIKEY populated from that secret.