Linear CLI

Interacts with Linear for issue tracking and project management using the

linear

Scope

• Use for Linear issue/project/teams management via the CLI or GraphQL (

  linear gql

  ).
• Prefer built-in commands over raw GraphQL unless functionality is missing.
• Keep defaults in sync with the user's config; do not hard-code team IDs/outputs.

Install & Setup

• Install:

  npm install -g @0xbigboss/linear-cli

• Auth:

  linear auth set

  or set

  LINEAR_API_KEY

• Defaults:

  linear config set default_team_id TEAM_KEY

  ,

  linear config set default_output json|table

  ,

  linear config set default_state_filter completed,canceled

• Inspect or reset defaults:

  linear config show

  ,

  linear config unset default_output

• Config path:

  ~/.config/linear/config.json

  (override with

  --config PATH

  or

  LINEAR_CONFIG

  )

Prerequisites

• CLI installed and on PATH
• Valid Linear API key available
• Team defaults set or provided per command (team key/UUID)

Hygiene

• Branches: Name as

  {TICKET}-{short-name}

  (e.g.,

  ENG-123-fix-auth

  ); prefer git worktrees for parallel work
• Commits: Use conventional commits; ticket ID in body or trailer, not subject
• Assignment: Assign yourself when starting work (

  linear issue update ENG-123 --assignee me --yes

  )
• Sub-issues: Set parent to associate related work (requires UUID:

  linear issue update ENG-123 --parent PARENT_UUID --yes

  )
• Scope creep: Create separate issues for discovered work; link with blocks relation (

  linear issue link ENG-123 --blocks ENG-456 --yes

  )
• Cycles/projects: Ask user preference when creating issues

Quick Recipes

List my issues

linear issues list --team TEAM_KEY --assignee me --human-time

Search issues

linear search "keyword" --team TEAM_KEY --limit 10

Create an issue

linear issue create --team TEAM_KEY --title "Fix bug" --yes
# Returns identifier (e.g., ENG-123)

View issue details

linear issue view ENG-123

Get issue as JSON for processing

linear issue view ENG-123 --json

Get issue with full context (for agents/analysis)

linear issue view ENG-123 --fields identifier,title,state,assignee,priority,url,description,parent,sub_issues,comments --json

List all teams

linear teams list

Verify authentication

linear auth test

List projects

linear projects list --limit 10

View or change CLI defaults

linear config show
linear config set default_output json
linear config unset default_state_filter

Add a comment to an issue

linear issue comment ENG-123 --body "Comment text here" --yes

# Or from a file/stdin
cat notes.md | linear issue comment ENG-123 --body-file - --yes

Create and manage a project

# Create project (team UUID required)
linear project create --team TEAM_UUID --name "My Project" --state planned --yes

# Update project state
linear project update PROJECT_ID --state started --yes

# Add issue to project
linear project add-issue PROJECT_ID ISSUE_UUID --yes

Command Reference

linear issues list

linear search "keyword"

linear issue view ID

linear issue create

linear issue update ID

linear issue link ID

linear issue comment ID

linear issue delete ID

linear projects list

linear project view ID

linear project create

linear project update ID

linear project delete ID

linear project add-issue

linear project remove-issue

linear teams list

linear me

linear gql

linear help CMD

*

--parent

Common Flags

• --team ID\|KEY

  - Specify team (required for most commands)

• --json

  - Output as JSON

• --yes

  - Confirm mutations without prompt

• --human-time

  - Show relative timestamps

• --fields LIST

  - Select specific fields

• --help

  - Show command help

Workflow: Creating and Linking Issues

Note:

--parent

linear issue view ID --json | jq -r '.issue.id'

Progress:
- [ ] List teams to get TEAM_KEY: `linear teams list`
- [ ] Create parent issue: `linear issue create --team KEY --title "Epic" --yes`
- [ ] Create child issue: `linear issue create --team KEY --title "Task" --yes`
- [ ] Get parent UUID: `linear issue view PARENT_ID --json | jq -r '.issue.id'`
- [ ] Set parent (UUID required): `linear issue update CHILD_ID --parent PARENT_UUID --yes`
- [ ] Create another issue to link: `linear issue create --team KEY --title "Blocked" --yes`
- [ ] Link blocking issue: `linear issue link ISSUE_ID --blocks OTHER_ID --yes`
- [ ] Verify: `linear issue view ISSUE_ID --json`

Common Gotchas

--team TEAM_KEY

linear auth test

--yes

issue view

--parent

ID format summary: Most commands accept identifiers (ENG-123). Exception:

--parent

Advanced Operations

For operations not covered by built-in commands, use

linear gql

• Add attachments - See

  graphql-recipes.md

  → "Attach URL to Issue"
• Upload files - See

  graphql-recipes.md

  → "Upload File"

Note: Adding comments is now available via

linear issue comment

issue update --parent

linear issue view ID --json

Finding IDs

Important:

issue update --parent

# Get issue UUID from identifier
linear issue view ENG-123 --json | jq -r '.issue.id'

# Current user UUID
linear me --json | jq -r '.viewer.id'

# All teams with UUIDs
linear teams list --json

# Issue full details including UUID
linear issue view ENG-123 --json

Or in Linear app: Cmd/Ctrl+K → "Copy model UUID"

JSON Output Structures

Commands with

--json

issue view ID

.issue

issue view ID --fields ...

.

issues list

.issues

.issues.nodes[]

project view ID

.project

projects list

.projects

.projects.nodes[]

teams list

.teams

.teams.nodes[]

me

.viewer

search

.issues

.issues.nodes[]

Null handling: Many fields can be null (name, description, dates, assignee). Use null-safe filters.

jq Patterns

# List all projects (correct path)
linear projects list --json | jq '.projects.nodes[]'

# Filter projects by name (null-safe)
linear projects list --json | jq '.projects.nodes[] | select(.name) | select(.name | ascii_downcase | contains("keyword"))'

# Get project names as array
linear projects list --json | jq '[.projects.nodes[].name]'

# Filter issues by title
linear issues list --team TEAM --json | jq '.issues.nodes[] | select(.title | ascii_downcase | contains("bug"))'

# Extract specific fields
linear issues list --team TEAM --json | jq '.issues.nodes[] | {id: .identifier, title, state: .state.name}'

# Get issue UUID from identifier
linear issue view ENG-123 --json | jq -r '.issue.id'

Common mistakes:

• .[]

  on root - use

  .projects.nodes[]

  or

  .issues.nodes[]

• test("pattern"; "i")

  on null - filter nulls first with

  select(.field)

• Escaping

  !=

  in shells - use

  select(.field)

  instead of

  select(.field != null)

Reference Files

• graphql-recipes.md

  - GraphQL mutations for attachments, relations, comments, file uploads

• troubleshooting.md

  - Common errors and debugging steps

External Links

• Linear API Docs
• Schema Explorer