/linear-cli

name: linear-cli
description: Use when the user wants to list, view, start, create, or update Linear issues from the terminal via schpet/linear-cli, including setup, auth, repo config, and safe read/write boundaries.

Linear CLI (schpet/linear-cli)

Overview

Use this skill to help the user work through a local [`linear`](https://github.com/schpet/linear-cli) installation from inside NextClaw.

This skill is intentionally decoupled:

• The skill owns explanation, onboarding, readiness checks, workflow choice, and risk handling.
• The `linear` CLI owns actual execution against Linear’s API and the user’s git or Jujutsu workspace.

From the user’s point of view, the experience should feel complete:

• install the CLI if needed,
• ensure authentication and project configuration,
• verify readiness with observable commands,
• then run the real task.

Do not pretend the environment is ready when it is not.

What This Skill Covers

• Issue workflows: list, view, start, create, update, delete, comments, PR helpers (when `gh` is available as documented upstream).
• Team, project, milestone, and document commands exposed by the installed CLI.
• Git branch–based “current issue” semantics and Jujutsu `Linear-issue` trailers when the user uses `jj`.
• First-use setup: API key, `linear auth login`, and `linear config` in the target repository.
• Readiness checks and bounded troubleshooting.

What This Skill Does Not Cover

• Inventing flags or subcommands that do not appear in `linear --help` or the installed CLI help for the relevant subcommand.
• Claiming Linear workspace permissions or plan limits the user does not have.
• Silently bypassing missing authentication or broken configuration.
• Silently triggering destructive or write actions without explicit user confirmation.
• Treating third-party CLI behavior as native NextClaw behavior.

First-Use Workflow

When the user asks for a `linear`-powered task, follow this order.

1. Classify the task

Classify the task into one of these:

• read-only (view, list, print id/url/title),
• write (create/update/delete issues, start work, comments, milestones, documents),
• VCS-assisted (branch creation, issue binding).

If the task does not fit what the CLI supports, say so clearly.

2. Check whether the CLI exists

Run:

command -v linear

If missing, explain that the CLI must be installed locally first. Prefer one of these install paths and stay consistent with the user’s platform and package preferences:

• Homebrew: `brew install schpet/tap/linear` (see upstream tap name in the [repository](https://github.com/schpet/linear-cli)).
• npm (project or global): install `@schpet/linear-cli` and invoke via `npx linear` / `pnpm exec linear` / `bunx linear` as appropriate.
• Deno: follow upstream `deno install` instructions from the [README](https://github.com/schpet/linear-cli/blob/main/README.md).

After installation, continue with readiness checks instead of jumping straight into the user task.

3. Confirm CLI version

Run:

linear --version

If this fails, treat the install as broken and fix that before API-backed tasks.

4. Authentication and configuration

The CLI needs a Linear API key and login state. The user creates a key under Linear account security settings (see upstream docs).

Guide the user through:

linear auth login

For repository-specific defaults (team, workspace slug, VCS mode), run from the target repo:

linear config

Configuration is resolved from `./linear.toml`, `./.linear.toml`, repo root, `.config/linear.toml`, and platform-appropriate user config paths as documented upstream. Environment variables override file values when both apply.

5. Readiness check

Prefer a lightweight read that hits the API after auth, for example:

linear team list

If this fails with authentication or permission errors, do not proceed to the user’s real task. Diagnose auth, workspace, or token scope first.

6. Respect “current issue” rules

The CLI derives the current issue from:

• **git**: issue id embedded in the branch name (for example `ENG-123-my-feature`),
• **jj**: `Linear-issue` trailer in commit metadata.

If the user expects “current issue” behavior but the branch or trailers do not match, explain the mismatch before running issue-scoped commands.

Safe Execution Rules

• Prefer read-only commands before write commands.
• For creates, updates, deletes, starts, comments, or other writes, ask for explicit confirmation first unless the user already gave a clear, scoped instruction for that write.
• Do not assume `gh` or a Git host CLI is installed; if the user wants `linear issue pr`, verify `gh` availability or follow upstream behavior transparently.
• If the user is in the wrong directory for `linear config` or issue context, say so and ask to switch to the intended repository root.

Troubleshooting

`linear` not found

• Explain that the CLI is not installed or not on `PATH`.
• Guide installation using one of the supported methods, then re-check with `command -v linear`.

Auth or API errors on read commands

• Confirm `linear auth login` completed successfully.
• Confirm API key is valid and not revoked.
• Confirm workspace and `team_id` / defaults match the user’s intent (`linear config` and env vars).

Wrong issue or empty “current issue”

• For git, verify the branch name contains the expected Linear issue id.
• For Jujutsu, verify `Linear-issue` trailers on the relevant commits.
• Offer `linear issue view <id>` when current-issue detection is unreliable.

Platform differences

• Treat path and config locations as different on Windows vs Unix; follow upstream config search order instead of assuming POSIX-only paths.

Success Criteria

The skill is working correctly when:

• the user understands that execution is performed by the local `linear` CLI against Linear,
• missing CLI, auth, or config is identified before