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
- [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
## 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 (defaults to current team)
```
### 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 (defaults to current team)
```
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)
```
## Subcommands
### create
> Create a new document
```
Usage: linear document create
Description:
Create a new document
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)
--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 (slug or name)
--issue <issue> - Filter by issue (identifier like TC-123)
--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
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)
-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
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
```
## 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
```
### 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> - Attach a file to an issue
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
> Attach a file to an issue
```
Usage: linear issue attach <issueId> <filepath>
Description:
Attach a file to an issue
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-t, --title <title> - Custom title for the attachment
-c, --comment <body> - Add a comment body linked to the 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 to an issue or reply to a comment
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 to an issue or reply to a comment
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 <id> - Parent comment ID for replies
-a, --attach <filepath> - Attach a file to the comment (can be used multiple times)
--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
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
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 associated with 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, or 'active'
--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 issue state (can be repeated for (Default: [ "unstarted" ], Values: "triage", "backlog",
multiple states) "unstarted", "started", "completed", "canceled")
--all-states - Show issues from all states
--sort <sort> - Sort order (can also be set via (Values: "manual", "priority")
LINEAR_ISSUE_SORT)
--team <team> - Team 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, or 'active'
--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, (Default: 50)
use 0 for unlimited)
--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
```
### 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 (can be repeated for multiple
teams)
--all-teams - Query across all teams
-s, --state <state> - Filter by issue state (can be repeated for multiple (Values: "triage", "backlog", "unstarted", "started",
states) "completed", "canceled")
--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, (Values: "manual", "priority")
not available with --search)
--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, or 'active'
--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 (Default: 50)
for unlimited)
--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
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)
--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 associated with the issue (if not your default team)
--project <project> - Project to assign the issue to (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 or the issue already has a project)
--cycle <cycle> - Cycle name, number, or 'active'
-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 <teamKey> - Team key for 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 <teamKey> - Team key to disambiguate labels with 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 <teamKey> - Filter by team (e.g., TC). Shows team-specific labels only.
--workspace - Show only workspace-level labels (not team-specific)
--all - Show all labels (both workspace and team)
-j, --json - Output as JSON
```
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)
```
### 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)
```
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>
```
## Adding Labels to Issues
```bash
# Add label to issue
linear issue update DEV-123 --label "Bug"
# Add multiple 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
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
```
## Subcommands
### create
> Create a new Linear project
```
Usage: linear project create
Description:
Create a new Linear project
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 (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
--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
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)
-s, --status <status> - Status (planned, started, paused, completed, canceled, backlog)
-l, --lead <lead> - Project lead (username, email, or @me)
--start-date <startDate> - Start date (YYYY-MM-DD)
--target-date <targetDate> - Target date (YYYY-MM-DD)
-t, --team <team> - Team key (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
```
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 <teamKey> - 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 [teamKey] - List team members
states [teamKey] - List workflow states for a team
```
## 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 <teamKey>
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 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
```
### members
> List team members
```
Usage: linear team members [teamKey]
Description:
List team members
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-a, --all - Include inactive members
```
### states
> List workflow states for a team
```
Usage: linear team states [teamKey]
Description:
List workflow states for a team
Options:
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-j, --json - Output as JSON
```
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.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
## 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.
## 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` requires a sort order — provide it via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Also requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first.
- `--no-pager` is only supported on `issue list` — passing it to other commands like `project list` will error.
## Using the Linear GraphQL API Directly
**Prefer the CLI for all supported operations.** The `api` command should only be used as a fallback for queries not covered by the CLI.
### Check the schema for available types and fields
Write the schema to a tempfile, then search it:
```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 } }"}'
```