schpet/linear-cli已通過檢查
SKILL DETAIL
linear-cli
schpet/linear-cli/linear-cli
Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.
安裝量 · 171查看來源
Installation
npx skills add https://github.com/schpet/linear-cli --skill linear-cli
技能檔案
SKILL.md
最近同步 · 2026年9月12日
references/api.md›
# api
> Make a raw GraphQL API request
## Usage
```
Usage: linear api [query]
Description:
Make a raw GraphQL API request
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--variable <variable> - Variable in key=value format (coerces booleans, numbers, null; @file reads from
path)
--variables-json <json> - JSON object of variables (merged with --variable, which takes precedence)
--paginate - Auto-paginate a single connection field using cursor pagination
--silent - Suppress response output (exit code still reflects errors)
```
references/auth.md›
# auth
> Manage Linear authentication
## Usage
```
Usage: linear auth
Description:
Manage Linear authentication
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
login - Add a workspace credential
logout [workspace] - Remove a workspace credential
list - List configured workspaces
default [workspace] - Set the default workspace
token - Print the configured API token
whoami - Print information about the authenticated user
migrate - Migrate plaintext credentials to system keyring
```
## Subcommands
### default
> Set the default workspace
```
Usage: linear auth default [workspace]
Description:
Set the default workspace
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### list
> List configured workspaces
```
Usage: linear auth list
Description:
List configured workspaces
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### login
> Add a workspace credential
```
Usage: linear auth login
Description:
Add a workspace credential
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-k, --key <key> - API key (prompted if not provided)
--plaintext - Store API key in credentials file instead of system keyring
```
### logout
> Remove a workspace credential
```
Usage: linear auth logout [workspace]
Description:
Remove a workspace credential
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-f, --force - Skip confirmation prompt
```
### migrate
> Migrate plaintext credentials to system keyring
```
Usage: linear auth migrate
Description:
Migrate plaintext credentials to system keyring
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### token
> Print the configured API token
```
Usage: linear auth token
Description:
Print the configured API token
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### whoami
> Print information about the authenticated user
```
Usage: linear auth whoami
Description:
Print information about the authenticated user
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
references/commands.md›
# Linear CLI Command Reference
## Commands
- [api](./api.md) - Make a raw GraphQL API request
- [auth](./auth.md) - Manage Linear authentication
- [config](./config.md) - Interactively generate .linear.toml configuration
- [cycle](./cycle.md) - Manage Linear team cycles
- [document](./document.md) - Manage Linear documents
- [initiative](./initiative.md) - Manage Linear initiatives
- [initiative-update](./initiative-update.md) - Manage initiative status updates (timeline posts)
- [issue](./issue.md) - Manage Linear issues
- [label](./label.md) - Manage Linear issue labels
- [markdown](./markdown.md) - Linear-flavored Markdown: mentions and collapsible sections
- [milestone](./milestone.md) - Manage Linear project milestones
- [project](./project.md) - Manage Linear projects
- [project-update](./project-update.md) - Manage project status updates
- [schema](./schema.md) - Print the GraphQL schema to stdout
- [team](./team.md) - Manage Linear teams
- [user](./user.md) - Manage Linear users
## Quick Reference
```bash
# Get help for any command
linear <command> --help
linear <command> <subcommand> --help
```
references/config.md›
# config
> Interactively generate .linear.toml configuration
## Usage
```
Usage: linear config
Description:
Interactively generate .linear.toml configuration
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
references/cycle.md›
# cycle
> Manage Linear team cycles
## Usage
```
Usage: linear cycle
Description:
Manage Linear team cycles
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list - List cycles for a team
view, v <cycleRef> - View cycle details
```
## Subcommands
### list
> List cycles for a team
```
Usage: linear cycle list
Description:
List cycles for a team
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--team <team> - Team key, name, or ID (defaults to current team)
-j, --json - Output as JSON
```
### view
> View cycle details
```
Usage: linear cycle view <cycleRef>
Description:
View cycle details
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--team <team> - Team key, name, or ID (defaults to current team)
-j, --json - Output as JSON
```
references/document.md›
# document
> Manage Linear documents
## Usage
```
Usage: linear document
Description:
Manage Linear documents
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list, l - List documents
view, v <id> - View a document's content
create, c - Create a new document
update, u <documentId> - Update an existing document
delete, d [documentId] - Delete a document (moves to trash)
comment - Manage document comments
```
## Subcommands
### comment
> Manage document comments
```
Usage: linear document comment
Description:
Manage document comments
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
add <document> - Add a comment or reply to a document (by ID or slug)
list <document> - List comments on a document (by ID or slug)
```
#### comment subcommands
##### add
```
Usage: linear document comment add <document>
Description:
Add a comment or reply to a document (by ID or slug)
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-b, --body <text> - Comment body text
--body-file <path> - Read comment body from a file (preferred for markdown content)
-p, --parent, --reply-to <commentId> - Reply to a top-level comment by ID (the reply joins that thread)
```
##### list
```
Usage: linear document comment list <document>
Description:
List comments on a document (by ID or slug)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
### create
> Create a new document
```
Usage: linear document create
Description:
Create a new document
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --title <title> - Document title (required)
-c, --content <content> - Markdown content (inline)
-f, --content-file <path> - Read content from file
--project <project> - Attach to project (UUID, slug ID, or name)
--issue <issue> - Attach to issue (identifier like TC-123)
--initiative <initiative> - Attach to initiative (UUID, slug ID, or name)
--team <team> - Attach to team (key, name, or ID); with --cycle, scopes the cycle lookup instead
--cycle <cycle> - Attach to cycle: name, number, 'active'/'now', 'next', 'previous', or a relative
offset like +1 (team from --team or config)
--release <release> - Attach to release (UUID, name, or version)
--icon <icon> - Document icon (emoji)
-i, --interactive - Interactive mode with prompts
```
### delete
> Delete a document (moves to trash)
```
Usage: linear document delete [documentId]
Description:
Delete a document (moves to trash)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --yes - Skip confirmation prompt
--bulk <ids...> - Delete multiple documents by slug or ID
--bulk-file <file> - Read document slugs/IDs from a file (one per line)
--bulk-stdin - Read document slugs/IDs from stdin
```
### list
> List documents
```
Usage: linear document list
Description:
List documents
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--project <project> - Filter by project (UUID, slug ID, or name)
--issue <issue> - Filter by issue (identifier like TC-123)
--initiative <initiative> - Filter by initiative (UUID, slug ID, or name)
--team <team> - Filter by team (key, name, or ID); with --cycle, scopes the cycle lookup instead
--cycle <cycle> - Filter by cycle: name, number, 'active'/'now', 'next', 'previous', or a relative
offset like +1 (team from --team or config)
--release <release> - Filter by release (UUID, name, or version)
--json - Output as JSON
--limit <limit> - Limit results (Default: 50)
```
### update
> Update an existing document
```
Usage: linear document update <documentId>
Description:
Update an existing document
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --title <title> - New title for the document
-c, --content <content> - New markdown content (inline)
-f, --content-file <path> - Read new content from file
--icon <icon> - New icon (emoji)
--project <project> - Re-point to project (UUID, slug ID, or name); replaces the current attachment
--issue <issue> - Re-point to issue (identifier like TC-123); replaces the current attachment
--initiative <initiative> - Re-point to initiative (UUID, slug ID, or name); replaces the current attachment
--team <team> - Re-point to team (key, name, or ID); with --cycle, scopes the cycle lookup
instead
--cycle <cycle> - Re-point to cycle: name, number, 'active'/'now', 'next', 'previous', or a
relative offset like +1 (team from --team or config)
--release <release> - Re-point to release (UUID, name, or version); replaces the current attachment
-e, --edit - Open current content in $EDITOR for editing
--force - Update content even when document comments may lose inline anchors
```
### view
> View a document's content
```
Usage: linear document view <id>
Description:
View a document's content
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--raw - Output raw markdown without rendering
-w, --web - Open document in browser
--json - Output full document as JSON
--no-download - Keep remote URLs instead of downloading files
```
references/initiative-update.md›
# initiative-update
> Manage initiative status updates (timeline posts)
## Usage
```
Usage: linear initiative-update
Description:
Manage initiative status updates (timeline posts)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
create, c <initiativeId> - Create a new status update for an initiative
list, l, ls <initiativeId> - List status updates for an initiative
```
## Subcommands
### create
> Create a new status update for an initiative
```
Usage: linear initiative-update create <initiativeId>
Description:
Create a new status update for an initiative
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--body <body> - Update content (markdown)
--body-file <path> - Read content from file
--health <health> - Health status (onTrack, atRisk, offTrack)
-i, --interactive - Interactive mode with prompts
```
### list
> List status updates for an initiative
```
Usage: linear initiative-update list <initiativeId>
Description:
List status updates for an initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
--limit <limit> - Limit results (Default: 10)
```
references/initiative.md›
# initiative
> Manage Linear initiatives
## Usage
```
Usage: linear initiative
Description:
Manage Linear initiatives
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list, ls - List initiatives
view, v <initiativeId> - View initiative details
create - Create a new Linear initiative
archive [initiativeId] - Archive a Linear initiative
update <initiativeId> - Update a Linear initiative
unarchive <initiativeId> - Unarchive a Linear initiative
delete [initiativeId] - Permanently delete a Linear initiative
add-project <initiative> <project> - Link a project to an initiative
remove-project <initiative> <project> - Unlink a project from an initiative
comment - Manage initiative comments
```
## Subcommands
### add-project
> Link a project to an initiative
```
Usage: linear initiative add-project <initiative> <project>
Description:
Link a project to an initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--sort-order <sortOrder> - Sort order within initiative
```
### archive
> Archive a Linear initiative
```
Usage: linear initiative archive [initiativeId]
Description:
Archive a Linear initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --force - Skip confirmation prompt
--bulk <ids...> - Archive multiple initiatives by ID, slug, or name
--bulk-file <file> - Read initiative IDs from a file (one per line)
--bulk-stdin - Read initiative IDs from stdin
```
### comment
> Manage initiative comments
```
Usage: linear initiative comment
Description:
Manage initiative comments
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
add <initiative> - Add a comment or reply to an initiative's discussion (by ID, slug, or name)
list <initiative> - List comments on an initiative (by ID, slug, or name)
```
#### comment subcommands
##### add
```
Usage: linear initiative comment add <initiative>
Description:
Add a comment or reply to an initiative's discussion (by ID, slug, or name)
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-b, --body <text> - Comment body text
--body-file <path> - Read comment body from a file (preferred for markdown content)
-p, --parent, --reply-to <commentId> - Reply to a top-level comment by ID (the reply joins that thread)
```
##### list
```
Usage: linear initiative comment list <initiative>
Description:
List comments on an initiative (by ID, slug, or name)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
### create
> Create a new Linear initiative
```
Usage: linear initiative create
Description:
Create a new Linear initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Initiative name (required)
-d, --description <description> - Initiative description
-s, --status <status> - Status: planned, active, completed (default: planned)
-o, --owner <owner> - Owner (username, email, or @me for yourself)
--target-date <targetDate> - Target completion date (YYYY-MM-DD)
-c, --color <color> - Color hex code (e.g., #5E6AD2)
--icon <icon> - Icon name
-i, --interactive - Interactive mode (default if no flags provided)
```
### delete
> Permanently delete a Linear initiative
```
Usage: linear initiative delete [initiativeId]
Description:
Permanently delete a Linear initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --force - Skip confirmation prompt
--bulk <ids...> - Delete multiple initiatives by ID, slug, or name
--bulk-file <file> - Read initiative IDs from a file (one per line)
--bulk-stdin - Read initiative IDs from stdin
```
### list
> List initiatives
```
Usage: linear initiative list
Description:
List initiatives
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-s, --status <status> - Filter by status (active, planned, completed)
--all-statuses - Show all statuses (default: active only)
-o, --owner <owner> - Filter by owner (username or email)
-w, --web - Open initiatives page in web browser
-a, --app - Open initiatives page in Linear.app
-j, --json - Output as JSON
--archived - Include archived initiatives
```
### remove-project
> Unlink a project from an initiative
```
Usage: linear initiative remove-project <initiative> <project>
Description:
Unlink a project from an initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --force - Skip confirmation prompt
```
### unarchive
> Unarchive a Linear initiative
```
Usage: linear initiative unarchive <initiativeId>
Description:
Unarchive a Linear initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --force - Skip confirmation prompt
```
### update
> Update a Linear initiative
```
Usage: linear initiative update <initiativeId>
Description:
Update a Linear initiative
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - New name for the initiative
-d, --description <description> - New description
--status <status> - New status (planned, active, completed, paused)
--owner <owner> - New owner (username, email, or @me)
--target-date <targetDate> - Target completion date (YYYY-MM-DD)
--color <color> - Initiative color (hex, e.g., #5E6AD2)
--icon <icon> - Initiative icon name
-i, --interactive - Interactive mode for updates
```
### view
> View initiative details
```
Usage: linear initiative view <initiativeId>
Description:
View initiative details
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-w, --web - Open in web browser
-a, --app - Open in Linear.app
-j, --json - Output as JSON
```
references/issue.md›
# issue
> Manage Linear issues
## Usage
```
Usage: linear issue
Description:
Manage Linear issues
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
id - Print the issue based on the current git branch
mine, list, l - List your issues
query, q - Query issues with structured filters
title [issueId] - Print the issue title
start [issueId] - Start working on an issue
view, v [issueId] - View issue details (default) or open in browser/app
url [issueId] - Print the issue URL
describe [issueId] - Print the issue title and Linear-issue trailer
commits [issueId] - Show all commits for a Linear issue (jj only)
pull-request, pr [issueId] - Create a GitHub pull request with issue details
delete, d [issueId] - Delete an issue
create - Create a linear issue
update [issueId] - Update a linear issue
comment - Manage issue comments
attach <issueId> <filepath> - Create a sidebar link attachment on an issue (images do not render inline)
link <urlOrIssueId> [url] - Link a URL to an issue
relation - Manage issue relations (dependencies)
agent-session - Manage agent sessions for an issue
```
## Subcommands
### agent-session
> Manage agent sessions for an issue
```
Usage: linear issue agent-session
Description:
Manage agent sessions for an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list [issueId] - List agent sessions for an issue
view, v <sessionId> - View agent session details
```
#### agent-session subcommands
##### list
```
Usage: linear issue agent-session list [issueId]
Description:
List agent sessions for an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
--status <status> - Filter by session status (Values: "pending", "active", "complete", "awaitingInput",
"error", "stale")
```
##### view
```
Usage: linear issue agent-session view <sessionId>
Description:
View agent session details
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
### attach
> Create a sidebar link attachment on an issue (images do not render inline)
```
Usage: linear issue attach <issueId> <filepath>
Description:
Create a sidebar link attachment on an issue (images do not render inline)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --title <title> - Custom title for the attachment
-c, --comment <body> - Create a linked comment with this body; the file remains a sidebar attachment
--public - Upload images to a public, unauthenticated URL (default: private,
workspace-members only)
```
### comment
> Manage issue comments
```
Usage: linear issue comment
Description:
Manage issue comments
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
add [issueId] - Add a comment or reply; images uploaded with --attach render inline
delete <commentId> - Delete a comment
update <commentId> - Update an existing comment
list [issueId] - List comments for an issue
```
#### comment subcommands
##### add
```
Usage: linear issue comment add [issueId]
Description:
Add a comment or reply; images uploaded with --attach render inline
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-b, --body <text> - Comment body text
--body-file <path> - Read comment body from a file (preferred for markdown content)
-p, --parent, --reply-to <commentId> - Reply to a top-level comment by ID (the reply joins that thread)
-a, --attach <filepath> - Upload a file and add its Markdown link to the comment (images render inline;
repeatable)
--public - Upload attached images to a public, unauthenticated URL (default: private,
workspace-members only)
```
##### delete
```
Usage: linear issue comment delete <commentId>
Description:
Delete a comment
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
##### list
```
Usage: linear issue comment list [issueId]
Description:
List comments for an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
##### update
```
Usage: linear issue comment update <commentId>
Description:
Update an existing comment
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-b, --body <text> - New comment body text
--body-file <path> - Read comment body from a file (preferred for markdown content)
```
### commits
> Show all commits for a Linear issue (jj only)
```
Usage: linear issue commits [issueId]
Description:
Show all commits for a Linear issue (jj only)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### create
> Create a linear issue
```
Usage: linear issue create
Description:
Create a linear issue
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--start - Start the issue after creation
-a, --assignee <assignee> - Assign the issue to 'self' or someone (by username or name)
--due-date <dueDate> - Due date of the issue
--parent <parent> - Parent issue (if any) as a team_number code
-p, --priority <priority> - Priority of the issue (1-4, descending priority)
--estimate <estimate> - Points estimate of the issue
-d, --description <description> - Description of the issue
--description-file <path> - Read description from a file (preferred for markdown content)
-l, --label <label> - Issue label associated with the issue. May be repeated.
--team <team> - Team (key, name, or ID) for the issue, if not your default team
--project <project> - Project for the issue (UUID, slug ID, or name)
-s, --state <state> - Workflow state for the issue (by name or type)
--milestone <milestone> - Project milestone (UUID, or name when --project is set)
--cycle <cycle> - Cycle name, number, 'active'/'now', 'next', 'previous', or a relative offset
like +1 (use --cycle=-1 for negatives)
--no-use-default-template - Do not use default template for the issue
--no-interactive - Disable interactive prompts
-t, --title <title> - Title of the issue
```
### delete
> Delete an issue
```
Usage: linear issue delete [issueId]
Description:
Delete an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-y, --confirm - Skip confirmation prompt
--bulk <ids...> - Delete multiple issues by identifier (e.g., TC-123 TC-124)
--bulk-file <file> - Read issue identifiers from a file (one per line)
--bulk-stdin - Read issue identifiers from stdin
```
### describe
> Print the issue title and Linear-issue trailer
```
Usage: linear issue describe [issueId]
Description:
Print the issue title and Linear-issue trailer
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-r, --references, --ref - Use 'References' instead of 'Fixes' for the Linear issue link
```
### id
> Print the issue based on the current git branch
```
Usage: linear issue id
Description:
Print the issue based on the current git branch
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### link
> Link a URL to an issue
```
Usage: linear issue link <urlOrIssueId> [url]
Description:
Link a URL to an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --title <title> - Custom title for the link
Examples:
Link a URL to issue detected from branch linear issue link https://github.com/org/repo/pull/123
Link a URL to a specific issue linear issue link ENG-123 https://github.com/org/repo/pull/123
Link with a custom title linear issue link ENG-123 https://example.com --title "Design doc"
```
### mine
> List your issues
```
Usage: linear issue mine
Description:
List your issues
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-s, --state <state> - Filter by workflow state type (triage, backlog, unstarted, started, completed, (Default: [ "unstarted" ])
canceled), name, or ID (can be repeated for multiple states)
--all-states - Show issues from all states
--sort <sort> - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT) (Values: "manual", "priority")
--team <team> - Team key, name, or ID to list issues for (if not your default team)
--project <project> - Filter by project (UUID, slug ID, or name)
--project-label <projectLabel> - Filter by project label name (shows issues from all projects with this label)
--cycle <cycle> - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative
offset like +1
--milestone <milestone> - Filter by project milestone (UUID, or name when --project is set)
-l, --label <label> - Filter by label name (can be repeated for multiple labels)
--limit <limit> - Maximum number of issues to fetch (default: 50, use 0 for unlimited) (Default: 50)
--created-after <date> - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)
--updated-after <date> - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)
-w, --web - Open in web browser
-a, --app - Open in Linear.app
--no-pager - Disable automatic paging for long output
```
### pull-request
> Create a GitHub pull request with issue details
```
Usage: linear issue pull-request [issueId]
Description:
Create a GitHub pull request with issue details
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--base <branch> - The branch into which you want your code merged
--draft - Create the pull request as a draft
-t, --title <title> - Optional title for the pull request (Linear issue ID will be prefixed)
--web - Open the pull request in the browser after creating it
--head <branch> - The branch that contains commits for your pull request
-T, --template <file> - Start the pull request body from this template file (the Linear issue URL is
appended)
--no-template - Ignore the pr_template config option for this pull request
```
### query
> Query issues with structured filters
```
Usage: linear issue query
Description:
Query issues with structured filters
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--search <term> - Full-text search term
--search-comments - Also search inside issue comments (requires --search)
--team <team> - Filter by team key, name, or ID (can be repeated for multiple teams)
--all-teams - Query across all teams
-s, --state <state> - Filter by workflow state type (triage, backlog, unstarted, started, completed,
canceled), name, or ID (can be repeated for multiple states)
--all-states - Show issues from all states (this is the default)
--assignee <assignee> - Filter by assignee (username)
-A, --all-assignees - Show issues for all assignees (this is the default)
-U, --unassigned - Show only unassigned issues
--sort <sort> - Sort order: manual or priority (default: priority, not available with --search) (Values: "manual", "priority")
--project <project> - Filter by project (UUID, slug ID, or name)
--project-label <projectLabel> - Filter by project label name (shows issues from all projects with this label)
--cycle <cycle> - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative
offset like +1
--milestone <milestone> - Filter by project milestone (UUID, or name when --project is set)
-l, --label <label> - Filter by label name (can be repeated for multiple labels)
--limit <limit> - Maximum number of issues to fetch (default: 50, use 0 for unlimited) (Default: 50)
--created-after <date> - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)
--updated-after <date> - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)
--include-archived - Include archived issues
-j, --json - Output results as JSON
--no-pager - Disable automatic paging for long output
```
### relation
> Manage issue relations (dependencies)
```
Usage: linear issue relation
Description:
Manage issue relations (dependencies)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
add <issueId> <relationType> <relatedIssueId> - Add a relation between two issues
delete <issueId> <relationType> <relatedIssueId> - Delete a relation between two issues
list [issueId] - List relations for an issue
```
#### relation subcommands
##### add
```
Usage: linear issue relation add <issueId> <relationType> <relatedIssueId>
Description:
Add a relation between two issues
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Examples:
Mark issue as blocked by another linear issue relation add ENG-123 blocked-by ENG-100
Mark issue as blocking another linear issue relation add ENG-123 blocks ENG-456
Mark issues as related linear issue relation add ENG-123 related ENG-456
Mark issue as duplicate linear issue relation add ENG-123 duplicate ENG-100
```
##### delete
```
Usage: linear issue relation delete <issueId> <relationType> <relatedIssueId>
Description:
Delete a relation between two issues
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
##### list
```
Usage: linear issue relation list [issueId]
Description:
List relations for an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### start
> Start working on an issue
```
Usage: linear issue start [issueId]
Description:
Start working on an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-A, --all-assignees - Show issues for all assignees
-U, --unassigned - Show only unassigned issues
-f, --from-ref <fromRef> - Git ref to create new branch from
-b, --branch <branch> - Custom branch name to use instead of the issue identifier
```
### title
> Print the issue title
```
Usage: linear issue title [issueId]
Description:
Print the issue title
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### update
> Update a linear issue
```
Usage: linear issue update [issueId]
Description:
Update a linear issue
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-a, --assignee <assignee> - Assign the issue to 'self' or someone (by username or name)
--unassign - Clear the issue's assignee (cannot be combined with --assignee)
--due-date <dueDate> - Due date of the issue. Use --clear-due-date to remove it
--clear-due-date - Remove the issue's due date (cannot be combined with --due-date)
--parent <parent> - Parent issue (if any) as a team_number code. Use --clear-parent to remove it
--clear-parent - Remove the issue's parent (cannot be combined with --parent)
-p, --priority <priority> - Priority of the issue (1-4, descending priority)
--estimate <estimate> - Points estimate of the issue. Use --clear-estimate to remove it
--clear-estimate - Remove the issue's estimate (cannot be combined with --estimate)
-d, --description <description> - Description of the issue
--description-file <path> - Read description from a file (preferred for markdown content)
-l, --label <label> - Issue label associated with the issue; replaces the issue's entire label set.
May be repeated. Use --add-label/--remove-label to change labels incrementally.
--add-label <label> - Add a label to the issue, keeping its existing labels. May be repeated.
--remove-label <label> - Remove a label from the issue, keeping its other labels (does not delete the
label from the team). May be repeated.
--team <team> - Team (key, name, or ID) to move the issue to
--project <project> - Project to assign the issue to (UUID, slug ID, or name). Use --clear-project to
remove it
--clear-project - Remove the issue from its project (cannot be combined with --project or
--milestone)
-s, --state <state> - Workflow state for the issue (by name or type)
--milestone <milestone> - Project milestone (UUID, or name when --project is set or the issue already has
a project). Use --clear-milestone to remove it
--clear-milestone - Remove the issue from its project milestone (cannot be combined with
--milestone)
--cycle <cycle> - Cycle name, number, 'active'/'now', 'next', 'previous', or a relative offset
like +1 (use --cycle=-1 for negatives). Use --clear-cycle to remove the issue
from its cycle
--clear-cycle - Remove the issue from its cycle
-t, --title <title> - Title of the issue
```
### url
> Print the issue URL
```
Usage: linear issue url [issueId]
Description:
Print the issue URL
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### view
> View issue details (default) or open in browser/app
```
Usage: linear issue view [issueId]
Description:
View issue details (default) or open in browser/app
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-w, --web - Open in web browser
-a, --app - Open in Linear.app
--no-comments - Exclude comments from the output
--show-resolved-threads - Include resolved comment threads in the output
--no-pager - Disable automatic paging for long output
-j, --json - Output issue data as JSON
--no-download - Keep remote URLs instead of downloading files
```
references/label.md›
# label
> Manage Linear issue labels
## Usage
```
Usage: linear label
Description:
Manage Linear issue labels
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list - List issue labels
create - Create a new issue label
delete <nameOrId> - Delete an issue label
```
## Subcommands
### create
> Create a new issue label
```
Usage: linear label create
Description:
Create a new issue label
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Label name (required)
-c, --color <color> - Color hex code (e.g., #EB5757)
-d, --description <description> - Label description
-t, --team <team> - Team key, name, or ID for a team-specific label (omit for workspace label)
-i, --interactive - Interactive mode (default if no flags provided)
```
### delete
> Delete an issue label
```
Usage: linear label delete <nameOrId>
Description:
Delete an issue label
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --team <team> - Team key, name, or ID to disambiguate labels with the same name
-f, --force - Skip confirmation prompt
```
### list
> List issue labels
```
Usage: linear label list
Description:
List issue labels
Options:
-h, --help - Show this help.
--team <team> - Filter by team key, name, or ID (e.g., TC). Shows that team's labels plus
workspace labels.
--workspace - Show only workspace-level labels (not team-specific)
--all - Show all labels (both workspace and team)
-j, --json - Output as JSON
```
references/markdown.md›
# markdown
> Linear-flavored Markdown: mentions and collapsible sections
## Usage
```
Usage: linear markdown
Description:
Linear-flavored Markdown: mentions and collapsible sections
These rules apply to comment bodies, issue descriptions, document content,
project overviews, and status update bodies.
MENTIONS
A resource's plain Linear URL becomes a linked mention. A literal `@name`, an
`@[Name](id)`, or a Markdown link such as `[Name](url)` does not — it stays
plain text and notifies nobody. Put the bare URL in the body:
https://linear.app/acme/profiles/someuser can you take a look?
RESOLVING PEOPLE
Look the person up in the relevant team first. The team can usually be
inferred from the issue identifier or the current directory:
linear team members ENG --json
Paste the selected member's `url` field verbatim. If the intended person is
not a member of that team, stop and confirm before searching the whole
workspace with `linear user list --json`; mentioning someone outside the team
is likely accidental.
To mention an issue, use its URL the same way:
linear issue url ENG-123
COLLAPSIBLE SECTIONS
Open a section with `+++ [title]` and close it with `+++`:
+++ [Server log]
Markdown content that is initially hidden.
+++
The square brackets around the title and the closing `+++` are both required.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
references/milestone.md›
# milestone
> Manage Linear project milestones
## Usage
```
Usage: linear milestone
Description:
Manage Linear project milestones
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list - List milestones for a project
view, v <milestone> - View milestone details. By default lists the first 10 attached issues from the
first page of 50; use --all to paginate the full set.
create - Create a new project milestone
update <id> - Update an existing project milestone
delete <id> - Delete a project milestone
```
## Subcommands
### create
> Create a new project milestone
```
Usage: linear milestone create --project <project> --name <name>
Description:
Create a new project milestone
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--project <project> - Project (UUID, slug ID, or name) (required)
--name <name> - Milestone name (required)
--description <description> - Milestone description
--target-date <date> - Target date (YYYY-MM-DD)
```
### delete
> Delete a project milestone
```
Usage: linear milestone delete <id>
Description:
Delete a project milestone
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-f, --force - Skip confirmation prompt
```
### list
> List milestones for a project
```
Usage: linear milestone list --project <project>
Description:
List milestones for a project
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--project <project> - Project (UUID, slug ID, or name) (required)
-j, --json - Output as JSON
```
### update
> Update an existing project milestone
```
Usage: linear milestone update <id>
Description:
Update an existing project milestone
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--name <name> - Milestone name
--description <description> - Milestone description
--target-date <date> - Target date (YYYY-MM-DD)
--sort-order <value> - Sort order relative to other milestones
--project <project> - Move to a different project (UUID, slug ID, or name)
```
### view
> View milestone details. By default lists the first 10 attached issues from the first page of 50; use --all to paginate the full set.
```
Usage: linear milestone view <milestone>
Description:
View milestone details. By default lists the first 10 attached issues from the first page of 50; use --all to paginate the full set.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--all - Fetch and list every issue attached to the milestone (paginates the Linear API).
--project <project> - Project for resolving a milestone name (UUID, slug ID, or name)
-j, --json - Output as JSON
```
references/organization-features.md›
# Organization Features
Detailed command reference for Linear CLI organization features: initiatives, labels, projects, and bulk operations.
## Initiative Management
```bash
# List initiatives (default: active only)
linear initiative list
linear initiative list --all-statuses
linear initiative list --status planned
# View initiative details
linear initiative view <id-or-slug>
# Create initiative
linear initiative create --name "Q1 Goals" --status active
linear initiative create -i # Interactive mode
# Archive/unarchive
linear initiative archive <id>
linear initiative unarchive <id>
# Link projects to initiatives
linear initiative add-project <initiative> <project>
linear initiative remove-project <initiative> <project>
```
## Label Management
```bash
# List labels (shows ID, name, color, team)
linear label list
linear label list --team DEV
linear label list --workspace # Workspace-level only
# Create label
linear label create --name "Bug" --color "#EB5757"
linear label create --name "Feature" --team DEV
# Delete label (by ID or name)
linear label delete <id>
linear label delete "Bug" --team DEV
```
## Project Management
```bash
# List projects
linear project list
# View project
linear project view <id>
# Create project
linear project create --name "New Feature" --team DEV
linear project create --name "Q1 Work" --team DEV --initiative "Q1 Goals"
linear project create -i # Interactive mode
```
## Bulk Operations
```bash
# Delete multiple issues
linear issue delete --bulk DEV-123 DEV-124 DEV-125
# Delete from file (one ID per line)
linear issue delete --bulk-file issues.txt
# Delete from stdin
echo -e "DEV-123\nDEV-124" | linear issue delete --bulk-stdin
# Archive multiple initiatives
linear initiative archive --bulk <id1> <id2>
```
## Updating Labels on Issues
```bash
# Add a label, keeping the issue's existing labels
linear issue update DEV-123 --add-label "Bug"
# Remove a label from this issue only (label delete removes it team-wide)
linear issue update DEV-123 --remove-label "sprint-42"
# Swap labels atomically in one update
linear issue update DEV-123 --remove-label "sprint-42" --add-label "sprint-43"
# Replace the entire label set with exactly these labels
linear issue update DEV-123 --label "Bug" --label "High Priority"
```
references/project-update.md›
# project-update
> Manage project status updates
## Usage
```
Usage: linear project-update
Description:
Manage project status updates
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
create, c <projectId> - Create a new status update for a project
list, l <projectId> - List status updates for a project
```
## Subcommands
### create
> Create a new status update for a project
```
Usage: linear project-update create <projectId>
Description:
Create a new status update for a project
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--body <body> - Update content (inline)
--body-file <path> - Read content from file
--health <health> - Project health status (onTrack, atRisk, offTrack)
-i, --interactive - Interactive mode with prompts
```
### list
> List status updates for a project
```
Usage: linear project-update list <projectId>
Description:
List status updates for a project
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--json - Output as JSON
--limit <limit> - Limit results (Default: 10)
```
references/project.md›
# project
> Manage Linear projects
## Usage
```
Usage: linear project
Description:
Manage Linear projects
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list - List projects
view, v <projectId> - View project details
create - Create a new Linear project
update <projectId> - Update a Linear project
delete <projectId> - Delete (trash) a Linear project
comment - Manage project comments
```
## Subcommands
### comment
> Manage project comments
```
Usage: linear project comment
Description:
Manage project comments
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
add <project> - Add a comment or reply to a project's discussion (by ID, slug, or name)
list <project> - List comments on a project (by ID, slug, or name)
```
#### comment subcommands
##### add
```
Usage: linear project comment add <project>
Description:
Add a comment or reply to a project's discussion (by ID, slug, or name)
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-b, --body <text> - Comment body text
--body-file <path> - Read comment body from a file (preferred for markdown content)
-p, --parent, --reply-to <commentId> - Reply to a top-level comment by ID (the reply joins that thread)
```
##### list
```
Usage: linear project comment list <project>
Description:
List comments on a project (by ID, slug, or name)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
### create
> Create a new Linear project
```
Usage: linear project create
Description:
Create a new Linear project
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Project name (required)
-d, --description <description> - Project description (max 255 characters, enforced by Linear's API)
-f, --description-file <path> - Read project description from file (still subject to the 255-character API
limit)
--content <markdown> - Project overview markdown
--content-file <path> - Read project overview markdown from a file
-t, --team <team> - Team key, name, or ID (required, can be repeated for multiple teams)
-l, --lead <lead> - Project lead (username, email, or @me)
-s, --status <status> - Project status (planned, started, paused, completed, canceled, backlog)
--start-date <startDate> - Start date (YYYY-MM-DD)
--target-date <targetDate> - Target completion date (YYYY-MM-DD)
--priority <priority> - Project priority (none, urgent, high, medium, low)
--label <label> - Project label associated with the project. May be repeated.
--member <user> - Project member (username, email, display name, or @me). May be repeated.
--icon <icon> - Project icon
--color <color> - Project color as a HEX string
--initiative <initiative> - Add to initiative immediately (ID, slug, or name)
-i, --interactive - Interactive mode (default if no flags provided)
-j, --json - Output created project as JSON
```
### delete
> Delete (trash) a Linear project
```
Usage: linear project delete <projectId>
Description:
Delete (trash) a Linear project
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-f, --force - Skip confirmation prompt
```
### list
> List projects
```
Usage: linear project list
Description:
List projects
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--team <team> - Filter by team key, name, or ID
--all-teams - Show projects from all teams
--status <status> - Filter by status name
-w, --web - Open in web browser
-a, --app - Open in Linear.app
-j, --json - Output as JSON
```
### update
> Update a Linear project
```
Usage: linear project update <projectId>
Description:
Update a Linear project
Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,
and `[Name](url)` do not. Get a person's URL from the `url` field of
`linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
Run `linear markdown` for collapsible sections and the full reference.
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Project name
-d, --description <description> - Project description (max 255 characters, enforced by Linear's API)
-f, --description-file <path> - Read project description from file (still subject to the 255-character API
limit)
--content <markdown> - Project overview markdown
--content-file <path> - Read project overview markdown from a file
-s, --status <status> - Status (planned, started, paused, completed, canceled, backlog)
-l, --lead <lead> - Project lead (username, email, or @me). Use --clear-lead to remove it
--clear-lead - Remove the project's lead (cannot be combined with --lead)
--start-date <startDate> - Start date (YYYY-MM-DD). Use --clear-start-date to remove it
--clear-start-date - Remove the project's start date (cannot be combined with --start-date)
--target-date <targetDate> - Target date (YYYY-MM-DD). Use --clear-target-date to remove it
--clear-target-date - Remove the project's target date (cannot be combined with --target-date)
-t, --team <team> - Team key, name, or ID (can be repeated for multiple teams)
--label <label> - Replace the project's labels. May be repeated to set multiple labels.
```
### view
> View project details
```
Usage: linear project view <projectId>
Description:
View project details
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-w, --web - Open in web browser
-a, --app - Open in Linear.app
-j, --json - Output as JSON
```
references/schema.md›
# schema
> Print the GraphQL schema to stdout
## Usage
```
Usage: linear schema
Description:
Print the GraphQL schema to stdout
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--json - Output as JSON introspection result instead of SDL
-o, --output <file> - Write schema to file instead of stdout
```
references/team.md›
# team
> Manage Linear teams
## Usage
```
Usage: linear team
Description:
Manage Linear teams
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
create - Create a linear team
delete <team> - Delete a Linear team
list - List teams
id - Print the configured team id
autolinks - Configure GitHub repository autolinks for Linear issues with this team prefix
members [team] - List team members (team by key, name, or ID)
states [team] - List workflow states for a team (by key, name, or ID)
```
## Subcommands
### autolinks
> Configure GitHub repository autolinks for Linear issues with this team prefix
```
Usage: linear team autolinks
Description:
Configure GitHub repository autolinks for Linear issues with this team prefix
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### create
> Create a linear team
```
Usage: linear team create
Description:
Create a linear team
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Name of the team
-d, --description <description> - Description of the team
-k, --key <key> - Team key (if not provided, will be generated from name)
--private - Make the team private
--no-interactive - Disable interactive prompts
```
### delete
> Delete a Linear team
```
Usage: linear team delete <team>
Description:
Delete a Linear team
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
--move-issues <targetTeam> - Move all issues to another team (key, name, or ID) before deletion
-y, --force - Skip confirmation prompt
```
### id
> Print the configured team id
```
Usage: linear team id
Description:
Print the configured team id
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
```
### list
> List teams
```
Usage: linear team list
Description:
List teams
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-w, --web - Open in web browser
-a, --app - Open in Linear.app
-j, --json - Output as JSON
```
### members
> List team members (team by key, name, or ID)
```
Usage: linear team members [team]
Description:
List team members (team by key, name, or ID)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-a, --all - Include inactive members
-j, --json - Output as JSON; a member's url mentions them when pasted into Markdown
```
### states
> List workflow states for a team (by key, name, or ID)
```
Usage: linear team states [team]
Description:
List workflow states for a team (by key, name, or ID)
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
references/user.md›
# user
> Manage Linear users
## Usage
```
Usage: linear user
Description:
Manage Linear users
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
Commands:
list - List members of the workspace
```
## Subcommands
### list
> List members of the workspace
```
Usage: linear user list
Description:
List members of the workspace
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-a, --all - Include inactive members
-j, --json - Output as JSON; a member's url mentions them when pasted into Markdown. This
searches the whole workspace — prefer `linear team members <TEAM>`, and
confirm before mentioning someone outside the team
```
scripts/generate-docs.ts›
#!/usr/bin/env -S deno run --allow-run --allow-read --allow-write
/**
* Generates markdown documentation from `linear --help` output.
* Run periodically as the CLI evolves to keep skill references up to date.
*/
import { dirname, join } from "@std/path"
const SCRIPT_DIR = dirname(new URL(import.meta.url).pathname)
const SKILL_DIR = join(SCRIPT_DIR, "..")
const REFERENCES_DIR = join(SKILL_DIR, "references")
const SKILL_MD = join(SKILL_DIR, "SKILL.md")
const SKILL_TEMPLATE = join(SKILL_DIR, "SKILL.template.md")
// Files to preserve (not generated from help)
const PRESERVED_FILES = ["organization-features.md"]
// Commands to skip (shell completions, not useful for docs)
const SKIP_COMMANDS = ["completions"]
interface CommandInfo {
name: string
description: string
help: string
subcommands: CommandInfo[]
}
interface RunResult {
success: boolean
stdout: string
stderr: string
}
interface HelpResult {
help: string
failure: string | null
}
interface DiscoveryResult {
command: CommandInfo
failures: string[]
}
async function run(cmd: string[]): Promise<RunResult> {
try {
const command = new Deno.Command(cmd[0], {
args: cmd.slice(1),
stdout: "piped",
stderr: "piped",
env: { NO_COLOR: "1" }, // Disable ANSI colors
})
const result = await command.output()
return {
success: result.success,
stdout: new TextDecoder().decode(result.stdout).trim(),
stderr: new TextDecoder().decode(result.stderr).trim(),
}
} catch (error) {
// Deno.Command throws (e.g. NotFound) when the binary is missing
return {
success: false,
stdout: "",
stderr: error instanceof Error ? error.message : String(error),
}
}
}
function stripAnsi(str: string): string {
// Remove ANSI escape codes (in case NO_COLOR doesn't work)
// deno-lint-ignore no-control-regex
return str.replace(/\x1b\[[0-9;]*m/g, "")
}
function stripVersion(str: string): string {
// Remove "Version: X.Y.Z" lines from help output to avoid churn on version bumps
return str.replace(/^Version:.*\n?/gm, "").replace(/\n+$/, "")
}
function byName(a: { name: string }, b: { name: string }): number {
if (a.name < b.name) return -1
if (a.name > b.name) return 1
return 0
}
function lastSegment(name: string): string {
return name.split(" ").at(-1) ?? name
}
function parseCommands(helpText: string): string[] {
const lines = helpText.split("\n")
const start = lines.findIndex((line) => line.startsWith("Commands:"))
if (start === -1) {
return []
}
// Command lines look like " command, alias - Description". Collect names
// until the first blank line after the section starts; blank lines before
// the first command are ignored.
return lines.slice(start + 1).reduce<{ names: string[]; done: boolean }>(
(state, line) => {
if (state.done) {
return state
}
const match = line.match(/^\s{2}([a-z][-a-z]*)(?:,|\s)/)
if (match) {
return { names: [...state.names, match[1]], done: false }
}
if (state.names.length > 0 && line.trim() === "") {
return { names: state.names, done: true }
}
return state
},
{ names: [], done: false },
).names
}
async function getCommandHelp(cmdPath: string[]): Promise<HelpResult> {
const result = await run(["linear", ...cmdPath, "--help"])
if (!result.success) {
const label = ["linear", ...cmdPath].join(" ")
return {
help: "",
failure: `\`${label} --help\` failed: ${result.stderr || "no output"}`,
}
}
return { help: stripVersion(stripAnsi(result.stdout)), failure: null }
}
async function discoverCommand(cmdPath: string[]): Promise<DiscoveryResult> {
const { help, failure } = await getCommandHelp(cmdPath)
const name = cmdPath.join(" ")
// Extract description from help text
const descMatch = help.match(/Description:\s*\n\s*(.+)/)
const description = descMatch ? descMatch[1].trim() : ""
// Discover subcommands recursively
const subcommandNames = parseCommands(help)
const childResults = await Promise.all(
subcommandNames.map((subcmd) => discoverCommand([...cmdPath, subcmd])),
)
// Sort by name so output order is stable regardless of help order
const subcommands = childResults.map((child) => child.command).sort(byName)
const failures = [
...(failure ? [failure] : []),
...childResults.flatMap((child) => child.failures),
]
return {
command: { name, description, help, subcommands },
failures,
}
}
function fencedBlock(content: string): string[] {
return ["```", content, "```"]
}
function renderSubSubcommand(subsub: CommandInfo): string[] {
return [
"",
`##### ${lastSegment(subsub.name)}`,
"",
...fencedBlock(subsub.help),
]
}
function renderSubcommand(sub: CommandInfo): string[] {
const subName = lastSegment(sub.name)
const descriptionLines = sub.description ? [`> ${sub.description}`, ""] : []
// Handle 3-level deep commands (e.g., issue comment add)
const nestedLines = sub.subcommands.length > 0
? [
"",
`#### ${subName} subcommands`,
...sub.subcommands.flatMap(renderSubSubcommand),
]
: []
return [
"",
`### ${subName}`,
"",
...descriptionLines,
...fencedBlock(sub.help),
...nestedLines,
]
}
function generateCommandDoc(cmd: CommandInfo): string {
const cmdName = cmd.name.replace(/^linear /, "")
const subcommandLines = cmd.subcommands.length > 0
? ["", "## Subcommands", ...cmd.subcommands.flatMap(renderSubcommand)]
: []
return [
`# ${cmdName}`,
"",
`> ${cmd.description}`,
"",
"## Usage",
"",
...fencedBlock(cmd.help),
...subcommandLines,
].join("\n")
}
function generateIndex(commands: CommandInfo[]): string {
const commandLines = commands.map((cmd) => {
const cmdName = cmd.name.replace(/^linear /, "")
return `- [${cmdName}](./${cmdName}.md) - ${cmd.description}`
})
return [
"# Linear CLI Command Reference",
"",
"## Commands",
"",
...commandLines,
"",
"## Quick Reference",
"",
"```bash",
"# Get help for any command",
"linear <command> --help",
"linear <command> <subcommand> --help",
"```",
].join("\n") + "\n"
}
function flattenCommandPaths(cmd: CommandInfo): string[] {
return [`linear ${cmd.name}`, ...cmd.subcommands.flatMap(flattenCommandPaths)]
}
function generateCommandsSection(commands: CommandInfo[]): string {
return commands
.map((cmd) => flattenCommandPaths(cmd).join("\n"))
.join("\n\n")
}
function generateReferenceToc(commands: CommandInfo[]): string {
return commands
.map((cmd) =>
`- [${cmd.name}](references/${cmd.name}.md) - ${cmd.description}`
)
.join("\n")
}
async function generateSkillMd(commands: CommandInfo[]): Promise<string> {
const template = await Deno.readTextFile(SKILL_TEMPLATE)
return template
.replace("{{COMMANDS}}", generateCommandsSection(commands))
.replace("{{REFERENCE_TOC}}", generateReferenceToc(commands))
}
async function writeReferences(commands: CommandInfo[]): Promise<void> {
await Deno.mkdir(REFERENCES_DIR, { recursive: true })
const generated = new Map<string, string>([
...commands.map((cmd): [string, string] => {
const filename = `${cmd.name.replace(/^linear /, "")}.md`
return [filename, generateCommandDoc(cmd) + "\n"]
}),
["commands.md", generateIndex(commands)],
])
// Write every generated file before removing anything so a partial failure
// cannot leave the references directory gutted.
for (const [filename, content] of generated) {
await Deno.writeTextFile(join(REFERENCES_DIR, filename), content)
console.log(` Generated: ${filename}`)
}
// Remove stale generated docs: markdown no longer produced and not preserved.
const keep = new Set([...generated.keys(), ...PRESERVED_FILES])
for await (const entry of Deno.readDir(REFERENCES_DIR)) {
if (entry.isFile && entry.name.endsWith(".md") && !keep.has(entry.name)) {
await Deno.remove(join(REFERENCES_DIR, entry.name))
}
}
}
async function main() {
console.log("Generating Linear CLI documentation...")
// Check linear is available
const versionResult = await run(["linear", "--version"])
if (!versionResult.success) {
throw new Error(
`linear CLI not found or failed to run: ${
versionResult.stderr || "is it installed?"
}`,
)
}
console.log(`Linear CLI: ${stripAnsi(versionResult.stdout)}`)
// Auto-discover top-level commands from `linear --help`
console.log("Discovering commands...")
const topLevelHelp = await getCommandHelp([])
if (topLevelHelp.failure) {
throw new Error(topLevelHelp.failure)
}
const topLevelNames = parseCommands(topLevelHelp.help).filter(
(cmd) => !SKIP_COMMANDS.includes(cmd),
)
console.log(`Found ${topLevelNames.length} top-level commands`)
const discovered = await Promise.all(
topLevelNames.map((cmd) => discoverCommand([cmd])),
)
// Abort before writing if any help fetch failed, so broken output is never
// committed to the docs.
const failures = discovered.flatMap((result) => result.failures)
if (failures.length > 0) {
throw new Error(
`Aborting: ${failures.length} command help fetch(es) failed:\n${
failures.join("\n")
}`,
)
}
const commands = discovered.map((result) => result.command).sort(byName)
// Render SKILL.md from its template before writing anything, so a missing or
// broken template aborts before writeReferences prunes any stale docs.
console.log("Generating SKILL.md from template...")
const skillContent = await generateSkillMd(commands)
// Generate markdown files
console.log("Generating markdown files...")
await writeReferences(commands)
await Deno.writeTextFile(SKILL_MD, skillContent)
console.log(" Generated: SKILL.md")
// Format all generated files
console.log("\nFormatting generated files...")
const fmtResult = await run(["deno", "fmt", SKILL_DIR])
if (!fmtResult.success) {
// Fail hard: unformatted docs would break `deno fmt --check` in CI once committed.
throw new Error(
`Failed to format generated files: ${
fmtResult.stderr || "unknown error"
}`,
)
}
console.log(`\nDone! Generated ${commands.length + 2} files.`)
}
if (import.meta.main) {
main().catch((error: unknown) => {
// Print a concise message, not a raw stack trace, on any abort path.
console.error(
`Error: ${error instanceof Error ? error.message : String(error)}`,
)
Deno.exit(1)
})
}
SKILL.md›
---
name: linear-cli
description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.
allowed-tools: Bash(linear:*), Bash(curl:*)
---
# Linear CLI
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:
```bash
linear --version
```
If not installed globally, you can run it without installing via npx:
```bash
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
## Common Tasks
Copy-pasteable recipes for the most frequent flows. Prefer these dedicated commands over `linear api` — reach for the GraphQL fallback only when no dedicated command or flag covers the operation.
### Query issues with filters
`issue query` searches across all assignees and supports structured filters that can be combined:
```bash
linear issue query --team ENG --state started --json
linear issue query --project "Mobile App" --state backlog --state triage --unassigned
linear issue query --assignee sam --label bug --updated-after 2026-01-01
```
Note: `linear issue list` is an alias of `issue mine` and only shows _your_ issues — use `issue query` for anything scoped to other people or a whole team/project.
### List my issues
```bash
linear issue mine --state started --sort priority
```
### Create an issue
```bash
linear issue create --team ENG --title "Fix login redirect" \
--description-file ./description.md --no-interactive
```
Write multi-line markdown to a file and pass `--description-file` (see the markdown section below); `--no-interactive` avoids prompts in scripted use.
### Update an issue's state, assignee, or labels
```bash
linear issue update ENG-123 --state "In Review" --assignee sam
linear issue update ENG-123 --unassign
linear issue update ENG-123 --add-label security # add, keep existing labels
linear issue update ENG-123 --remove-label sprint-42 # detach; does not delete the label
linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43 # atomic swap
linear issue update ENG-123 --label infra --label security # replaces the label set
```
### Add a comment
```bash
linear issue comment add ENG-123 --body-file ./comment.md
```
### Attach an image or screenshot so it is visible inline
```bash
linear issue comment add ENG-123 --attach ./screenshot.png
```
This uploads the image and embeds it in a comment, where Linear renders it inline. Do not use `linear issue attach` when the image must be visible: that command creates a sidebar link attachment and does not render images inline.
### View an issue / get its URL
```bash
linear issue view ENG-123 # details incl. comments
linear issue view ENG-123 --json # structured output
linear issue url ENG-123 # print just the URL
```
## 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:**
```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 for comments
linear issue comment add ENG-123 --body-file /tmp/comment.md
```
**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
## Linear Markdown Features
### Mention people and resources with plain URLs
Linear turns a resource's **plain Linear URL** in Markdown into a linked mention. A literal `@name`, `@[Name](id)`, or a Markdown link such as `[Name](url)` does not create the same mention. Put the plain URL directly in the comment or description:
```markdown
https://linear.app/yourworkspace/profiles/someuser could you review this? https://linear.app/yourworkspace/issue/ENG-123 is related.
```
Resolve people within the relevant team first. The team can usually be inferred from the issue identifier or current directory:
```bash
linear team members ENG --json
```
Use the selected member's `url` field verbatim in the Markdown. If the intended person is not a member of that team, stop and confirm before searching the whole workspace with `linear user list --json`; mentioning someone outside the team is likely accidental. For issues, use `linear issue url ENG-123` and include that plain URL.
### Add collapsible sections
Open a collapsible section with `+++ [title]` and close it with `+++`:
```markdown
+++ [Server log]
Markdown content that is initially hidden.
+++
```
The square brackets around the title and the closing `+++` are required.
## Available Commands
Compact command list, generated from `linear --help`:
```bash
linear api
linear auth
linear auth default
linear auth list
linear auth login
linear auth logout
linear auth migrate
linear auth token
linear auth whoami
linear config
linear cycle
linear cycle list
linear cycle view
linear document
linear document comment
linear document comment add
linear document comment list
linear document create
linear document delete
linear document list
linear document update
linear document view
linear initiative
linear initiative add-project
linear initiative archive
linear initiative comment
linear initiative comment add
linear initiative comment list
linear initiative create
linear initiative delete
linear initiative list
linear initiative remove-project
linear initiative unarchive
linear initiative update
linear initiative view
linear initiative-update
linear initiative-update create
linear initiative-update list
linear issue
linear issue agent-session
linear issue agent-session list
linear issue agent-session view
linear issue attach
linear issue comment
linear issue comment add
linear issue comment delete
linear issue comment list
linear issue comment update
linear issue commits
linear issue create
linear issue delete
linear issue describe
linear issue id
linear issue link
linear issue mine
linear issue pull-request
linear issue query
linear issue relation
linear issue relation add
linear issue relation delete
linear issue relation list
linear issue start
linear issue title
linear issue update
linear issue url
linear issue view
linear label
linear label create
linear label delete
linear label list
linear markdown
linear milestone
linear milestone create
linear milestone delete
linear milestone list
linear milestone update
linear milestone view
linear project
linear project comment
linear project comment add
linear project comment list
linear project create
linear project delete
linear project list
linear project update
linear project view
linear project-update
linear project-update create
linear project-update list
linear schema
linear team
linear team autolinks
linear team create
linear team delete
linear team id
linear team list
linear team members
linear team states
linear user
linear user list
```
## Reference Documentation
- [api](references/api.md) - Make a raw GraphQL API request
- [auth](references/auth.md) - Manage Linear authentication
- [config](references/config.md) - Interactively generate .linear.toml configuration
- [cycle](references/cycle.md) - Manage Linear team cycles
- [document](references/document.md) - Manage Linear documents
- [initiative](references/initiative.md) - Manage Linear initiatives
- [initiative-update](references/initiative-update.md) - Manage initiative status updates (timeline posts)
- [issue](references/issue.md) - Manage Linear issues
- [label](references/label.md) - Manage Linear issue labels
- [markdown](references/markdown.md) - Linear-flavored Markdown: mentions and collapsible sections
- [milestone](references/milestone.md) - Manage Linear project milestones
- [project](references/project.md) - Manage Linear projects
- [project-update](references/project-update.md) - Manage project status updates
- [schema](references/schema.md) - Print the GraphQL schema to stdout
- [team](references/team.md) - Manage Linear teams
- [user](references/user.md) - Manage Linear users
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.
Some commands have required flags that aren't obvious. Notable examples:
- `issue list` sorts by priority by default — override via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first (`linear team list --json` maps team names to their `key` and `id`).
- `--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:
```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 } }"}'
```
SKILL.template.md›
---
name: linear-cli
description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.
allowed-tools: Bash(linear:*), Bash(curl:*)
---
# Linear CLI
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:
```bash
linear --version
```
If not installed globally, you can run it without installing via npx:
```bash
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
## Common Tasks
Copy-pasteable recipes for the most frequent flows. Prefer these dedicated commands over `linear api` — reach for the GraphQL fallback only when no dedicated command or flag covers the operation.
### Query issues with filters
`issue query` searches across all assignees and supports structured filters that can be combined:
```bash
linear issue query --team ENG --state started --json
linear issue query --project "Mobile App" --state backlog --state triage --unassigned
linear issue query --assignee sam --label bug --updated-after 2026-01-01
```
Note: `linear issue list` is an alias of `issue mine` and only shows _your_ issues — use `issue query` for anything scoped to other people or a whole team/project.
### List my issues
```bash
linear issue mine --state started --sort priority
```
### Create an issue
```bash
linear issue create --team ENG --title "Fix login redirect" \
--description-file ./description.md --no-interactive
```
Write multi-line markdown to a file and pass `--description-file` (see the markdown section below); `--no-interactive` avoids prompts in scripted use.
### Update an issue's state, assignee, or labels
```bash
linear issue update ENG-123 --state "In Review" --assignee sam
linear issue update ENG-123 --unassign
linear issue update ENG-123 --add-label security # add, keep existing labels
linear issue update ENG-123 --remove-label sprint-42 # detach; does not delete the label
linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43 # atomic swap
linear issue update ENG-123 --label infra --label security # replaces the label set
```
### Add a comment
```bash
linear issue comment add ENG-123 --body-file ./comment.md
```
### Attach an image or screenshot so it is visible inline
```bash
linear issue comment add ENG-123 --attach ./screenshot.png
```
This uploads the image and embeds it in a comment, where Linear renders it inline. Do not use `linear issue attach` when the image must be visible: that command creates a sidebar link attachment and does not render images inline.
### View an issue / get its URL
```bash
linear issue view ENG-123 # details incl. comments
linear issue view ENG-123 --json # structured output
linear issue url ENG-123 # print just the URL
```
## 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:**
```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 for comments
linear issue comment add ENG-123 --body-file /tmp/comment.md
```
**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
## Linear Markdown Features
### Mention people and resources with plain URLs
Linear turns a resource's **plain Linear URL** in Markdown into a linked mention. A literal `@name`, `@[Name](id)`, or a Markdown link such as `[Name](url)` does not create the same mention. Put the plain URL directly in the comment or description:
```markdown
https://linear.app/yourworkspace/profiles/someuser could you review this? https://linear.app/yourworkspace/issue/ENG-123 is related.
```
Resolve people within the relevant team first. The team can usually be inferred from the issue identifier or current directory:
```bash
linear team members ENG --json
```
Use the selected member's `url` field verbatim in the Markdown. If the intended person is not a member of that team, stop and confirm before searching the whole workspace with `linear user list --json`; mentioning someone outside the team is likely accidental. For issues, use `linear issue url ENG-123` and include that plain URL.
### Add collapsible sections
Open a collapsible section with `+++ [title]` and close it with `+++`:
```markdown
+++ [Server log]
Markdown content that is initially hidden.
+++
```
The square brackets around the title and the closing `+++` are required.
## Available Commands
Compact command list, generated from `linear --help`:
```bash
{{COMMANDS}}
```
## Reference Documentation
{{REFERENCE_TOC}}
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.
Some commands have required flags that aren't obvious. Notable examples:
- `issue list` sorts by priority by default — override via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first (`linear team list --json` maps team names to their `key` and `id`).
- `--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:
```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 } }"}'
```