--- name: linear-cli description: Use the linear-cli agent-native runtime to read and mutate Linear from Claude Code, Codex, or other agents. Use when the runtime needs default JSON output, startup discovery, dry-run previews, operation receipts, workflow-safe automation, or direct CLI control over Linear issues, projects, cycles, documents, notifications, webhooks, or related resources. allowed-tools: Bash(linear:*), Bash(curl:*) --- # Linear CLI An agent-native Linear runtime for the current `v3` execution model, with stable JSON contracts, startup discovery, dry-run previews, timeout-aware write semantics, source-adjacent intake, and git/jj workflow integration. ## Recommended Agent Loop When using this CLI from an agent runtime, prefer this order: 1. Discover command traits with `linear capabilities`; use `--compat v1` only when an older consumer still expects the trimmed legacy shape 2. Read Linear state with default-JSON core surfaces or `--json` 3. Preview writes with `--dry-run --json` when available 4. Apply writes on the default machine-readable surface, then inspect `operation`, `receipt`, and `error.details` 5. Inspect exit codes and `error.details` instead of parsing styled terminal text Prompt-driven human/debug flows are secondary and explicit. When a command supports prompts or editor entry, pass `--profile human-debug --interactive`; otherwise missing required inputs fail fast. Agent-safe execution semantics are now the default runtime behavior. `--text` and `--profile human-debug` are the explicit human/debug escape hatches for maintainers, and `--profile agent-safe` remains accepted for compatibility with older automation. When upstream tooling hands the runtime a normalized Slack, ticket, or similar source envelope, prefer `--context-file`, add `--apply-triage` if that envelope already contains deterministic team/state/label hints, and choose `--autonomy-policy` explicitly when the wrapper needs suggest-only or preview-required staging. Recommended supporting docs: - [../../docs/agent-first.md](../../docs/agent-first.md) - [../../docs/v2-to-v3-migration-cookbook.md](../../docs/v2-to-v3-migration-cookbook.md) - [../../docs/json-contracts.md](../../docs/json-contracts.md) - [../../docs/stdin-policy.md](../../docs/stdin-policy.md) ## Prerequisites The `linear` command must be available on PATH. To check: ```bash linear --version ``` If not installed, follow the instructions at:\ https://github.com/kyaukyuai/linear-cli?tab=readme-ov-file#install ## Best Practices for Markdown Content When working with issue descriptions or comment bodies that contain markdown, prefer file-based flags for existing files and stdin for generated pipeline content: - Use `--description-file` for `issue create` and `issue update` commands when the content already exists on disk - Use `--body-file` for `comment add` and `comment update` commands when the content already exists on disk - Pipe stdin for generated markdown, for example `cat description.md | linear issue create --title "My Issue" --team ENG` **Why avoid large inline 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 in scripts and pipelines **Example workflow:** ```bash # 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 pipe generated markdown directly cat /tmp/description.md | linear issue create --title "My Issue" --team ENG # 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 ``` linear auth # Manage Linear authentication linear issue # Manage Linear issues linear team # Manage Linear teams linear project # Manage Linear projects linear project-update # Manage project status updates linear cycle # Manage Linear team cycles linear milestone # Manage Linear project milestones linear initiative # Manage Linear initiatives linear initiative-update # Manage initiative status updates (timeline posts) linear label # Manage Linear issue labels linear document # Manage Linear documents linear notification # Manage Linear notifications linear webhook # Manage Linear webhooks linear workflow-state # Manage Linear workflow states linear user # Manage Linear users linear project-label # Manage Linear project labels linear config # Interactively generate .linear.toml configuration linear schema # Print the GraphQL schema to stdout linear api # Make a raw GraphQL API request linear capabilities # Describe the agent-facing command surface linear resolve # Resolve references without mutating Linear ``` ## Reference Documentation - [auth](references/auth.md) - Manage Linear authentication - [issue](references/issue.md) - Manage Linear issues - [team](references/team.md) - Manage Linear teams - [project](references/project.md) - Manage Linear projects - [project-update](references/project-update.md) - Manage project status updates - [cycle](references/cycle.md) - Manage Linear team cycles - [milestone](references/milestone.md) - Manage Linear project milestones - [initiative](references/initiative.md) - Manage Linear initiatives - [initiative-update](references/initiative-update.md) - Manage initiative status updates (timeline posts) - [label](references/label.md) - Manage Linear issue labels - [document](references/document.md) - Manage Linear documents - [notification](references/notification.md) - Manage Linear notifications - [webhook](references/webhook.md) - Manage Linear webhooks - [workflow-state](references/workflow-state.md) - Manage Linear workflow states - [user](references/user.md) - Manage Linear users - [project-label](references/project-label.md) - Manage Linear project labels - [config](references/config.md) - Interactively generate .linear.toml configuration - [schema](references/schema.md) - Print the GraphQL schema to stdout - [api](references/api.md) - Make a raw GraphQL API request - [capabilities](references/capabilities.md) - Describe the agent-facing command surface - [resolve](references/resolve.md) - Resolve references without mutating Linear For curated examples of organization features (initiatives, labels, projects, bulk operations), see [organization-features](references/organization-features.md). ## Discovering Options To see available subcommands and flags, run `--help` on any command: ```bash 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. For machine-readable discovery, prefer: ```bash linear capabilities linear capabilities --compat v1 ``` ## 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: ```bash 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. ```bash # 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`: ```bash 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

Description

Latest Changes

Install Linear CLI with One Click