SKILL.md

Linear CLI

Name: linear-cli
Author: schpet

A CLI to manage Linear issues from the command line, with git and jj integration.

Prerequisites

The linear command must be available on PATH. To check:

linear --version

If not installed globally, you can run it without installing via npx:

npx @schpet/linear-cli --version

All subsequent commands can be prefixed with npx @schpet/linear-cli in place of linear. Otherwise, follow the install instructions at:

https://github.com/schpet/linear-cli?tab=readme-ov-file#install

Best Practices for Markdown Content

When working with issue descriptions or comment bodies that contain markdown, always prefer using file-based flags instead of passing content as command-line arguments:

Use --description-file for issue create and issue update commands

Use --body-file for comment add and comment update commands

Why use file-based flags:

Ensures proper formatting in the Linear web UI

Avoids shell escaping issues with newlines and special characters

Prevents literal \n sequences from appearing in markdown

Makes it easier to work with multi-line content

Example workflow:

# Write markdown to a temporary file

cat > /tmp/description.md <<'EOF'

## Summary

- First item

- Second item

## Details

This is a detailed description with proper formatting.

EOF

# Create issue using the file

linear issue create --title "My Issue" --description-file /tmp/description.md

# Or for comments

linear issue comment add ENG-123 --body-file /tmp/comment.md

Only use inline flags (--description, --body) for simple, single-line content.

Available Commands

Compact command list, generated from linear --help:

linear auth

linear auth login

linear auth logout

linear auth list

linear auth default

linear auth token

linear auth whoami

linear auth migrate

linear issue

linear issue id

linear issue mine

linear issue query

linear issue title

linear issue start

linear issue view

linear issue url

linear issue describe

linear issue commits

linear issue pull-request

linear issue delete

linear issue create

linear issue update

linear issue comment

linear issue comment add

linear issue comment delete

linear issue comment update

linear issue comment list

linear issue attach

linear issue link

linear issue relation

linear issue relation add

linear issue relation delete

linear issue relation list

linear issue agent-session

linear issue agent-session list

linear issue agent-session view

linear team

linear team create

linear team delete

linear team list

linear team id

linear team autolinks

linear team members

linear project

linear project list

linear project view

linear project create

linear project update

linear project delete

linear project-update

linear project-update create

linear project-update list

linear cycle

linear cycle list

linear cycle view

linear milestone

linear milestone list

linear milestone view

linear milestone create

linear milestone update

linear milestone delete

linear initiative

linear initiative list

linear initiative view

linear initiative create

linear initiative archive

linear initiative update

linear initiative unarchive

linear initiative delete

linear initiative add-project

linear initiative remove-project

linear initiative-update

linear initiative-update create

linear initiative-update list

linear label

linear label list

linear label create

linear label delete

linear document

linear document list

linear document view

linear document create

linear document update

linear document delete

linear config

linear schema

linear api

Reference Documentation

auth - Manage Linear authentication

issue - Manage Linear issues

team - Manage Linear teams

project - Manage Linear projects

project-update - Manage project status updates

cycle - Manage Linear team cycles

milestone - Manage Linear project milestones

initiative - Manage Linear initiatives

initiative-update - Manage initiative status updates (timeline posts)

label - Manage Linear issue labels

document - Manage Linear documents

config - Interactively generate .linear.toml configuration

schema - Print the GraphQL schema to stdout

api - Make a raw GraphQL API request

For curated examples of organization features (initiatives, labels, projects, bulk operations), see organization-features.

Discovering Options

To see available subcommands and flags, run --help on any command:

linear --help

linear issue --help

linear issue list --help

linear issue create --help

Each command has detailed help output describing all available flags and options.

Some commands have required flags that aren't obvious. Notable examples:

issue list requires a sort order — provide it via --sort (valid values: manual, priority), the issue_sort config option, or the LINEAR_ISSUE_SORT env var. Also requires --team <key> unless the team can be inferred from the directory — if unknown, run linear team list first.

--no-pager is only supported on issue list — passing it to other commands like project list will error.

Using the Linear GraphQL API Directly

Prefer the CLI for all supported operations. The api command should only be used as a fallback for queries not covered by the CLI.

Check the schema for available types and fields

Write the schema to a tempfile, then search it:

linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"

grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"

grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

Make a GraphQL request

Important: GraphQL queries containing non-null type markers (e.g. String followed by an exclamation mark) must be passed via heredoc stdin to avoid escaping issues. Simple queries without those markers can be passed inline.

# Simple query (no type markers, so inline is fine)

linear api '{ viewer { id name email } }'

# Query with variables — use heredoc to avoid escaping issues

linear api --variable teamId=abc123 <<'GRAPHQL'

query($teamId: String!) { team(id: $teamId) { name } }

GRAPHQL

# Search issues by text

linear api --variable term=onboarding <<'GRAPHQL'

query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }

GRAPHQL

# Numeric and boolean variables

linear api --variable first=5 <<'GRAPHQL'

query($first: Int!) { issues(first: $first) { nodes { title } } }

GRAPHQL

# Complex variables via JSON

linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'

query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }

GRAPHQL

# Pipe to jq for filtering

linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

Advanced: Using curl directly

For cases where you need full HTTP control, use linear auth token:

curl -s -X POST https://api.linear.app/graphql \

  -H "Content-Type: application/json" \

  -H "Authorization: $(linear auth token)" \

  -d '{"query": "{ viewer { id } }"}'

linear-cli