Linear Cli

Configure for this repo

linear config

This writes a .linear.toml in the repo root with the team ID and workspace slug. The file is checked into git so all agents and developers share the same config.

Starting a Task from an Issue

When given an issue ID (e.g. ENG-123):

# Read the full issue -- description, state, assignee, labels, comments
linear issue view ENG-123

# Get just the title (useful for branch names or commit messages)
linear issue title ENG-123

# Get the Linear URL
linear issue url ENG-123

The agent should read the issue description to understand requirements before starting implementation.

Task Lifecycle

On start: Move the issue to "In Progress" immediately when beginning implementation.

linear issue update ENG-123 -s started
# or via GraphQL if CLI fails (see Updating Issues below)

On deploy to production: Move to "In Review" only after the deploy has fully completed and the change is live on production. Never update Linear state speculatively or immediately after pushing — a reviewer loading the issue will open the production site, which must already reflect the change.

The required sequence:

1. Push to telecine main (or merge PR)
2. Block on scripts/wait-for-telecine-action until the deploy job completes successfully
3. Only then move to "In Review" and add a comment

# From monorepo/ — MUST complete before touching Linear
scripts/wait-for-telecine-action

# Then move to In Review
linear api <<'GRAPHQL'
mutation {
  issueUpdate(id: "EF2-123", input: { stateId: "2717b5fe-9ea0-429f-8edd-cf8eabe0551d" }) { success }
}
GRAPHQL

linear issue comment add EF2-123 -b "Deployed to production. <one-line summary of what changed>"

The comment should be a single sentence describing what was implemented or fixed, not a list of commits.

Searching and Listing Issues

# List unstarted issues assigned to you (default)
# --sort is required: manual or priority (NOT "updated")
linear issue list --sort priority

# List issues in a specific state
linear issue list -s started --sort priority
linear issue list -s backlog --sort priority
linear issue list --all-states --sort priority

# List issues for all assignees
linear issue list -A --sort priority

# List unassigned issues
linear issue list -U --sort priority

# Filter by project -- requires exact name match; use GraphQL if not found
linear issue list --project "Project Name" --sort priority --team ENG

# Filter by team (required if no .linear.toml in repo)
linear issue list --team ENG --sort priority

# Limit results
linear issue list --limit 10 --sort priority

List issues in a project via GraphQL (preferred for project browsing)

The CLI --project filter is fragile (exact name match, requires team). Use GraphQL instead:

# First find the project ID
linear api <<'GRAPHQL'
query {
  projects(first: 50) {
    nodes { id name }
  }
}
GRAPHQL

# Then fetch its issues
linear api <<'GRAPHQL'
query {
  project(id: "<id>") {
    issues(first: 50) {
      nodes { identifier title state { name } assignee { name } priority }
    }
  }
}
GRAPHQL

Free-text search via GraphQL

The CLI doesn't have a built-in search command, but the api subcommand exposes the full GraphQL API:

linear api --variable term="onboarding" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } assignee { name } }
  }
}
GRAPHQL

Pipe to jq for filtering:

linear api --variable term="bug" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } }
  }
}
GRAPHQL

Updating Issues

# Mark as started (sets state to "In Progress")
# NOTE: linear issue update fails with "Could not determine team key from issue ID"
# for non-standard prefixes (e.g. EF2-123). Use GraphQL mutation instead (see below).
linear issue update ENG-123 -s started

# Update title or description
linear issue update ENG-123 -t "New title"
linear issue update ENG-123 --description-file /tmp/desc.md

# Add a comment
linear issue comment add ENG-123 -b "Started implementation"

# For multi-line markdown comments, use a file
linear issue comment add ENG-123 --body-file /tmp/comment.md

Update issue state via GraphQL (when CLI update fails)

# Find the state ID first
linear api <<'GRAPHQL'
query {
  workflowStates(filter: { name: { eq: "Done" } }) {
    nodes { id name team { key } }
  }
}
GRAPHQL

# Then update one or more issues in a single mutation
linear api <<'GRAPHQL'
mutation {
  issueUpdate(id: "EF2-123", input: { stateId: "<state-id>" }) { success }
}
GRAPHQL

# Batch update multiple issues
linear api <<'GRAPHQL'
mutation {
  a: issueUpdate(id: "EF2-436", input: { stateId: "<state-id>" }) { success }
  b: issueUpdate(id: "EF2-435", input: { stateId: "<state-id>" }) { success }
}
GRAPHQL

Creating Issues

# Interactive (prompts for details)
linear issue create

# Non-interactive
linear issue create -t "Fix rendering bug" --description-file /tmp/desc.md -a self -s unstarted

# Create and immediately start working
linear issue create -t "Investigate flaky test" --start

Always use --description-file or --body-file for multi-line markdown content to avoid shell escaping issues.

Discovering CLI Options

Every command supports --help:

linear --help
linear issue --help
linear issue list --help
linear issue create --help

The CLI has extensive subcommands beyond issues -- linear team, linear project, linear document, linear label, linear milestone. Run --help on any of them.

Workspace Reference

Use these IDs directly in mutations — no need to query for them first.

Users

Workflow States (team: EF2)

Projects

When to Use This Skill

• User provides a Linear issue ID and wants to begin work on it
• User asks to find or search for Linear issues
• User wants to see what's assigned to them or what's in a specific state
• User asks to update an issue's status or add a comment
• Agent needs to read issue requirements before starting implementation