Linear CLI (schpet/linear-cli)

Overview

Use this skill to help the user work through a local linear 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).
• 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.

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 task execution,
• a lightweight API read succeeds before heavier workflows when appropriate,
• write operations wait for explicit confirmation when required,
• and the real task runs only after the environment is truly ready.