Linear

Linear

Use this skill whenever the task involves Linear and the linear CLI is available or should be made available. Prefer CLI workflows for listing, creating, viewing, and updating Linear records when the requested task can be completed without the browser UI.

These notes are grounded against @schpet/linear-cli. The latest published version is 2.0.0; flag names differ from 1.9.1 in the auth subcommand. Always run linear auth login --help before attempting non-interactive auth, as flag names vary between versions.

Typical Goals

• Check existing issues before creating duplicates.
• Create issues with clear titles, descriptions, team assignment, labels, projects, priorities, or assignees when requested.
• View, update, comment on, assign, transition, or close issues.
• List teams, labels, and projects to resolve names, keys, and IDs.
• Configure reusable CLI authentication on a persistent VM.
• Use the Linear web UI only when the CLI lacks a needed operation or setup requires a personal API key.

Operating Principles

• Inspect linear --help and subcommand help when command syntax is uncertain; CLI versions can differ.
• Prefer structured or explicit output flags when supported by the installed CLI. In 1.9.1, linear issue view --json and linear label list --json support JSON; linear issue list does not.
• Prefer managed OAuth over browser/API-key setup. When Linear credentials are missing, expired, or insufficient, use RequestOAuthAuthorization to connect the user's Linear account, then pass the saved credential to Exec.credential_env.
• Check existing issues before creating a new one unless the user explicitly asks to create a new issue.
• Do not claim an issue was found, created, or updated until a linear command succeeds and returns an identifier or URL.
• If auth or permissions fail, report the concrete blocker and the command that exposed it.
• Avoid relying on browser login alone as proof of CLI access; verify with real CLI reads.

Managed OAuth

Before doing browser-assisted setup or asking for an API key, check whether a Linear OAuth credential already exists:

1. Call ListOAuthCredentials.
2. If a linear credential is available and active, use its alias in Exec.credential_env; replace "default" below with the actual alias returned by ListOAuthCredentials:

   [{"env_var":"LINEAR_ACCESS_TOKEN","provider":"linear","alias":"default","value":"access_token"}]

3. If no usable Linear credential exists, call RequestOAuthAuthorization with provider: "linear", a short stable alias such as "default", and a concise reason. Request scopes for the intended work; omit scopes for read-only access, or pass ["read", "write"] when mutations such as creating, updating, commenting, or assigning issues are needed.
4. Share the returned authorization_url with the user and wait for them to confirm they completed authorization.
5. Call CompleteOAuthAuthorization with the returned state. If it returns completed, retry the Linear command with Exec.credential_env using the returned alias. If it returns pending, ask the user to finish the browser flow. If it returns failed or expired, start a fresh authorization flow.

Managed OAuth keeps tokens out of the transcript. Do not print the token or try to read it directly; inject it only for the subprocess that needs Linear access.

Initial Checks

linear --help
linear auth list
linear auth whoami
linear team list

If linear is not installed, check whether npx can run the CLI:

npx -y @schpet/linear-cli --help

Issue Discovery And Triage

linear issue list in version 1.9.1 lists issues but does not expose a full-text search flag. Use filters to narrow the candidate set, then inspect likely matches. If true full-text search is required, use the Linear web UI or API after noting the CLI limitation.

linear issue list --help
linear issue list --all-states --all-assignees --limit 50 --no-pager
linear issue list --all-states --all-assignees --team CUE --limit 50 --no-pager
linear issue list --state started --state unstarted --assignee self --no-pager

Useful issue list flags in 1.9.1:

• --state <state> repeatable, with values triage, backlog, unstarted, started, completed, canceled.
• --all-states.
• --assignee <username>, --all-assignees, and --unassigned.
• --team <team>.
• --project <project>.
• --sort manual|priority.
• --limit <limit>.
• --no-pager.

Inspect candidates with JSON when downstream parsing is useful:

linear issue view <issue-id-or-key>
linear issue view <issue-id-or-key> --json --no-comments --no-download
linear issue url <issue-id-or-key>
linear issue title <issue-id-or-key>

When deciding whether an issue is a duplicate, compare:

• User-visible symptom.
• Affected product, platform, or workflow.
• Recency and status.
• Existing owner, team, label, or project context.

Create Issues

Before creating, resolve the target team and optional metadata:

linear team list
linear label list --all
linear label list --all --json
linear project list --all-teams

Create the issue non-interactively when the requested fields are known. Keep the description specific and actionable:

linear issue create --team CUE --title "Investigate login timeout on macOS" --description "..." --label Bug --priority 2 --no-interactive

Useful issue create flags in 1.9.1:

• --title <title>.
• --description <description>.
• --team <team>.
• --assignee <assignee> or --assignee self.
• --label <label> repeatable.
• --project <project>.
• --state <state>.
• --priority <priority> where 1 is highest and 4 is lowest.
• --estimate <estimate>.
• --due-date <dueDate>.
• --parent <team_number>.
• --start.
• --no-interactive.

After creation, capture and report:

• Issue key or identifier.
• Title.
• URL.
• Team and status if available.

Update, Comment, And Transition

Inspect command help before mutating records:

linear issue update --help
linear issue comment --help
linear issue comment add --help

Common operations include:

• Add a comment with investigation notes or a user-provided update.
• Assign or unassign an issue.
• Change status or workflow state.
• Add labels, project, priority, estimate, parent, or due date.
• Close or reopen an issue.

Examples:

linear issue update CUE-123 --state started --assignee self
linear issue update CUE-123 --label Bug --label Regression --priority 1
linear issue comment add CUE-123 --body "Investigated the timeout path; next step is checking session refresh."
linear issue comment list CUE-123

After mutation, re-view the issue or rely on the command's returned identifier/URL to verify the change.

Projects, Teams, And Workflow Context

Use lookup commands to avoid guessing names or IDs:

linear team list
linear team members CUE
linear label list --all
linear label list --team CUE
linear label list --workspace
linear project list --all-teams
linear project list --team CUE
linear project view <projectId>

The 1.9.1 top-level command set includes auth, issue, team, project, project-update, milestone, initiative, initiative-update, label, document, config, and schema. It does not expose top-level user or cycle commands.

If workflow-state names are uncertain, inspect issue details and use linear issue update --state <state> with a known state name or type.

Authentication And Setup

If linear auth whoami already works, do not recreate credentials. If setup is required, prefer the managed OAuth flow above and run Linear commands with Exec.credential_env. Configure @schpet/linear-cli with a manually obtained API key only when managed OAuth is unavailable or the CLI cannot use the injected OAuth token.

Success criteria for setup:

• Interactive login state for linear.app exists if browser-based API key creation is needed.
• @schpet/linear-cli is installed or invokable through a persistent wrapper.
• A Linear API key is available to the CLI.
• linear auth whoami succeeds.
• A real read command such as linear team list succeeds.

Setup workflow:

1. Check for Node/npm and prior CLI state with linear auth list.
2. Install @schpet/linear-cli globally with npm install -g @schpet/linear-cli.
3. After global install, the binary may land in the nvm version bin path rather than a PATH directory. Check with npm bin -g or ls $(npm root -g)/../bin/linear. Prefer creating a symlink into a persistent PATH directory over an npx wrapper (which re-downloads on every invocation):

   ln -sf "$(npm bin -g)/linear" /home/sprite/.local/bin/linear

4. Run linear auth login --help to confirm the exact flag names for the installed version before attempting non-interactive auth.
5. In local VM environments without a system keyring, always pass --plaintext to linear auth login so credentials are stored in a file rather than hanging on keyring access:

   linear auth login --key <api-key> --plaintext

6. Restrict permissions on any file containing the token. Store a backup in /home/sprite/.config/linear/env.sh exporting LINEAR_API_KEY, chmod 600. Avoid printing linear auth token unless the user explicitly needs the token.
7. Verify with linear auth whoami and linear team list.