Command-line interface for the Linear project management API.
brew install iatsiuk/tap/linear-cli
Download pre-built binaries for Linux and macOS from GitHub Releases.
Requirements: Go 1.25+
git clone https://github.com/iatsiuk/linear-cli
cd linear-cli
make build
The binary is placed at ./linear-cli. Move it to a directory in your PATH:
mv linear-cli /usr/local/bin/linear
linear-cli requires a Linear personal API key.
Generate one at: Linear Settings -> API -> Personal API keys
linear auth
Prompts for your API key and saves it to the config file.
linear auth status
Shows whether an API key is configured (masked).
Config file location: ~/.config/linear-cli/config.yaml
Format:
api_key: lin_api_xxxx
default_team: ""Set LINEAR_API_KEY to override the config file value without modifying it:
export LINEAR_API_KEY=lin_api_xxxx
linear auth status
The environment variable takes precedence over the config file.
linear [command] [flags]
Flags:
--json Output in JSON format
--version Show version
-h, --help Show help
Manage Linear issues with the issue subcommand.
linear issue list [flags]
Flags:
--team string filter by team key (e.g. ENG)
--assignee string filter by assignee display name
--state string filter by workflow state name
--priority int filter by priority: 0=none, 1=urgent, 2=high, 3=normal, 4=low
--limit int maximum number of issues to return (default 50)
--include-archived include archived issues
--order-by string sort order: createdAt|updatedAt (default "updatedAt")
--json output as JSON array
--created-after string issues created after date
--created-before string issues created before date
--updated-after string issues updated after date
--updated-before string issues updated before date
--due-after string issues with due date after
--due-before string issues with due date before
--completed-after string issues completed after date
--completed-before string issues completed before date
--priority-gte int minimum priority value
--priority-lte int maximum priority value
--my only issues assigned to me
--no-assignee only issues with no assignee
--no-project only issues with no project
--no-cycle only issues with no cycle
--or combine filters with OR logic (default is AND)
Output columns: ID, Title, Status, Priority, Assignee
Date flags accept:
7d, 14d N days ago (-P7D, -P14D)
2w, 4w N weeks ago (-P2W, -P4W)
1m, 3m N months ago (-P1M, -P3M)
today current date (ISO 8601)
yesterday yesterday's date (ISO 8601)
2026-03-01 exact ISO 8601 date
-P30D ISO 8601 duration (passed directly to API)
Examples:
linear issue list --created-after 7d --priority-gte 2 --no-assignee
linear issue list --team ENG --my --state "In Progress"
linear issue list --due-before today --priority-lte 2
linear issue list --updated-after 2w --or --no-project --no-cycle
linear issue show <identifier> [flags]
Displays all fields for an issue: identifier, number, title, status, priority, team, assignee, due date, estimate, labels, URL, created/updated timestamps, description, parent issue (if set), project (if set), cycle (if set), creator (if set), branch name, customer ticket count, and all lifecycle timestamps (started, completed, canceled, archived, triage started, snoozed until, added to cycle/project/team). SLA fields (type, breach time, high/medium risk thresholds, started at) are shown when present. Trashed status is shown when true.
Flags:
--json output as JSON object
Example:
linear issue show ENG-42
linear issue create --title <title> --team <team> [flags]
Flags:
--title string issue title (required)
--team string team key or ID (required)
--description string issue description in markdown
--assignee string assignee name, email, UUID, or "me"
--state string workflow state name or ID
--priority int priority: 0=none, 1=urgent, 2=high, 3=normal, 4=low
--label stringArray label name or ID (repeatable)
--due-date string due date (YYYY-MM-DD)
--estimate int complexity estimate (integer)
--cycle string cycle ID
--project string project name or ID
--parent string parent issue identifier or ID
--json output created issue as JSON
Example:
linear issue create --title "Fix login bug" --team ENG --priority 1 --assignee me
linear issue update <identifier> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--title string issue title
--description string issue description in markdown
--assignee string assignee name, email, UUID, or "me"
--state string workflow state name or ID
--priority int priority: 0=none, 1=urgent, 2=high, 3=normal, 4=low
--label stringArray set labels, replacing all existing (repeatable)
--add-label stringArray add label by name or ID (repeatable)
--remove-label stringArray remove label by name or ID (repeatable)
--due-date string due date (YYYY-MM-DD)
--estimate int complexity estimate (integer)
--cycle string cycle ID
--project string project name or ID
--parent string parent issue identifier or ID
--json output updated issue as JSON
Example:
linear issue update ENG-42 --state Done --assignee me
linear issue batch update [<id1> <id2> ...] [flags]
Updates multiple issues in a single API call. Accepts issue identifiers (e.g. ENG-42) as arguments or from stdin (one per line). Maximum 50 issues per batch.
Flags:
--assignee string assignee name, email, UUID, or "me"
--state string workflow state name or ID
--priority int priority: 0=none, 1=urgent, 2=high, 3=normal, 4=low
--label stringArray set labels, replacing all existing (repeatable)
--add-label stringArray add label by name or ID (repeatable)
--remove-label stringArray remove label by name or ID (repeatable)
--project string project name or ID
--cycle string cycle ID
--json output updated issues as JSON array
At least one change flag is required. --label cannot be combined with --add-label or --remove-label.
Note: --state resolves the state name within the team of the issues being updated. All issues in the batch must belong to the same team when --state is used.
Examples:
linear issue batch update ENG-1 ENG-2 ENG-3 --state Done
linear issue batch update ENG-10 ENG-11 --assignee me --priority 2
linear issue batch update ENG-5 ENG-6 --add-label bug --remove-label "needs triage"
echo -e "ENG-1\nENG-2\nENG-3" | linear issue batch update --state "In Review"
linear issue delete <identifier> [flags]
By default, moves the issue to trash (30-day grace period for recovery). Use --archive to archive instead.
Flags:
--archive archive the issue instead of trashing it
--yes skip confirmation prompt
Example:
linear issue delete ENG-42 --yes
linear issue delete ENG-42 --archive
Manage relations between issues with the issue relation subcommand.
linear issue relation list <issue-identifier>
Shows all outgoing and incoming relations for an issue.
Output columns: Type | Direction | Related Issue | Title
Example:
linear issue relation list ENG-42
linear issue relation create <issue-identifier> [flags]
Flags:
--related string identifier of the related issue (required)
--type string relation type: blocks|duplicate|related|similar (default "related")
--json output created relation as JSON
Relation types:
blocks- this issue blocks the related issueduplicate- this issue is a duplicate of the related issuerelated- issues are relatedsimilar- issues are similar
Examples:
linear issue relation create ENG-42 --related ENG-99 --type blocks
linear issue relation create ENG-42 --related ENG-10 --type duplicate
linear issue relation delete <relation-id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear issue relation delete abc123 --yes
linear issue branch [branch-name] [flags]
Looks up the Linear issue linked to a git branch name. If no branch name is provided, uses the current git branch (from git rev-parse --abbrev-ref HEAD).
Displays full issue details (same as issue show).
Flags:
--json output as JSON object
Examples:
linear issue branch
linear issue branch feature/eng-42-fix-login
Manage Linear notifications with the notification subcommand.
linear notification list [flags]
Flags:
--unread show only unread notifications
--limit int maximum number of notifications to fetch (default 50)
--json output as JSON array
Output columns: ID | Type | Created | Read
Examples:
linear notification list
linear notification list --unread
linear notification list --limit 20 --json
linear notification read [id] [flags]
Flags:
--all mark all notifications as read
Examples:
linear notification read abc123
linear notification read --all
linear notification archive [id] [flags]
Flags:
--all archive all notifications
Examples:
linear notification archive abc123
linear notification archive --all
Show organization info for the authenticated workspace.
linear org [flags]
Flags:
--json output as JSON object
Output fields: Name, URL key, Logo URL (if set).
Examples:
linear org
linear org --json
Show the currently authenticated user.
linear me [flags]
Flags:
--assigned show issues assigned to the current user
--created show issues created by the current user
--json output as JSON
Examples:
linear me
linear me --assigned
linear me --created
linear me --json
Output (default): Name, Email, Role, Active status, and team memberships. Output (--assigned/--created): table of issues with columns ID, Title, Status.
Manage Linear teams with the team subcommand.
linear team list [flags]
Flags:
--json output as JSON array
Output columns: Name, Key, Description, Cycles
linear team show <id|key> [flags]
Accepts a team UUID or team key (e.g. ENG).
Flags:
--json output as JSON object
Output fields: Name, Key, Cycles, Estimation, Description, Created, Updated.
Example:
linear team show ENG
Manage team membership with the team member subcommand.
linear team member list <team-key> [flags]
Flags:
--limit int maximum number of members to return (default 50)
--json output as JSON array
Output columns: Name | Email | Role
Example:
linear team member list ENG
linear team member add <team-key> <user>
The user argument accepts a display name, email, or UUID.
Example:
linear team member add ENG "Jane Smith"
linear team member add ENG jane@example.com
linear team member remove <team-key> <user> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear team member remove ENG jane@example.com --yes
Manage Linear projects with the project subcommand.
linear project list [flags]
Flags:
--team string filter by team key (e.g. ENG)
--status string filter by status (backlog|planned|started|paused|completed|canceled)
--health string filter by health (onTrack|atRisk|offTrack)
--limit int maximum number of projects to return (default 50)
--include-archived include archived projects
--order-by string sort order: createdAt|updatedAt (default "updatedAt")
--json output as JSON array
Output columns: Name | Status | Health | Progress% | Target Date
linear project show <id> [flags]
Flags:
--json output as JSON object
Output fields: Name, Status, Health, Progress, Teams, Creator, Start Date, Target Date, URL, Created, Updated, and description.
linear project create --name <name> --team <team> [flags]
Flags:
--name string project name (required)
--team stringArray team key or ID (repeatable, required)
--description string project description
--color string project color (hex)
--target-date string target date (YYYY-MM-DD)
--start-date string start date (YYYY-MM-DD)
--json output created project as JSON
Example:
linear project create --name "Q2 Launch" --team ENG --target-date 2026-06-30
linear project update <id> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--name string project name
--description string project description
--state string project state type or UUID (backlog|planned|started|paused|completed|canceled)
--target-date string target date (YYYY-MM-DD)
--start-date string start date (YYYY-MM-DD)
--json output updated project as JSON
Example:
linear project update abc123 --state started
linear project delete <id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear project delete abc123 --yes
Manage project status check-ins (ProjectUpdate entities) with the project update subcommand.
Note: project update here refers to status check-in records, not modifying project fields (use project update <id> --name ... for that).
linear project update list <project-id> [flags]
Accepts a project UUID or name.
Flags:
--limit int maximum number of check-ins to return (default 25)
--json output as JSON array
Output columns: Health | Author | Date | Body (truncated)
Example:
linear project update list abc123
linear project update create <project-id> [flags]
Flags:
--body string check-in body text (required)
--health string project health (onTrack|atRisk|offTrack)
--json output created check-in as JSON
Example:
linear project update create abc123 --body "All milestones on track." --health onTrack
linear project update archive <id>
Archives the check-in by its UUID. Archiving replaces the deprecated delete operation.
Example:
linear project update archive checkin-uuid-here
Manage project milestones with the project milestone subcommand.
linear project milestone list <project-id> [flags]
Flags:
--limit int maximum number of milestones to return (default 50)
--json output as JSON array
Output columns: Name | Status | Target Date | Description
Example:
linear project milestone list abc123
linear project milestone create <project-id> [flags]
Flags:
--name string milestone name (required)
--description string milestone description
--target-date string target date (YYYY-MM-DD)
--json output created milestone as JSON
Example:
linear project milestone create abc123 --name "Beta release" --target-date 2026-06-01
linear project milestone update <id> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--name string milestone name
--description string milestone description
--target-date string target date (YYYY-MM-DD)
--json output updated milestone as JSON
Example:
linear project milestone update milestone-uuid --target-date 2026-07-01
linear project milestone delete <id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear project milestone delete milestone-uuid --yes
Manage Linear cycles with the cycle subcommand.
linear cycle list --team <key> [flags]
Flags:
--team string filter by team key (e.g. ENG)
--limit int maximum number of cycles to return (default 50)
--include-archived include archived cycles
--order-by string sort order: createdAt|updatedAt (default "updatedAt")
--json output as JSON array
Output columns: # | Name | Start | End | Progress% | Status (Active/Past/Future)
linear cycle show <id> [flags]
Flags:
--json output as JSON object
Output fields: Number, Name, Status, Progress, Start, End, Team, and description.
linear cycle active --team <key> [flags]
Shows the currently active cycle for a team.
Flags:
--team string team key (required)
--json output as JSON object
Example:
linear cycle active --team ENG
Manage Linear issue labels with the label subcommand.
linear label list [flags]
Flags:
--team string filter by team key (e.g. ENG); omit to list all labels
--json output as JSON array
Output columns: Name | Color | Description | Team | Group
Example:
linear label list
linear label list --team ENG
linear label create --name <name> --color <hex> [flags]
Flags:
--name string label name (required)
--color string label color in hex format, e.g. #ff0000 (required)
--team string team key or ID (omit for workspace-level label)
--description string label description
--json output created label as JSON
Example:
linear label create --name "bug" --color "#e11d48" --team ENG
linear label update <id> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--name string label name
--color string label color in hex format
--description string label description
--json output updated label as JSON
Example:
linear label update abc123 --color "#f97316"
Manage Linear workflow states with the state subcommand.
linear state list --team <key> [flags]
Output is grouped by state type: Triage, Backlog, Unstarted, Started, Completed, Canceled.
Flags:
--team string team key (required)
--json output as JSON array
Output columns: Name | Type | Color
Example:
linear state list --team ENG
Manage Linear issue comments with the comment subcommand.
linear comment list <issue-identifier> [flags]
Flags:
--json output as JSON array
Output columns: Author | Date | Body (truncated). Replies (threaded comments) are prefixed with > .
Example:
linear comment list ENG-42
linear comment create <issue-identifier> --body <text> [flags]
Flags:
--body string comment body in markdown (required)
--parent string parent comment ID for threading (reply to a comment)
--json output created comment as JSON
Example:
linear comment create ENG-42 --body "Looks good, merging soon."
linear comment create ENG-42 --body "Agreed." --parent abc123
linear comment update <comment-id> --body <text> [flags]
Flags:
--body string new comment body in markdown (required)
--json output updated comment as JSON
Example:
linear comment update abc123 --body "Revised: looks good, merging next sprint."
linear comment delete <comment-id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear comment delete abc123 --yes
Manage Linear users with the user subcommand.
linear user list [flags]
Flags:
--include-guests include guest users (excluded by default)
--include-disabled include disabled/deactivated users
--json output as JSON array
Output columns: Name, Email, Role, Active
linear user show <id> [flags]
Accepts a user UUID.
Flags:
--json output as JSON object
Output fields: Name, Email, Role, Active, Created, Updated.
Example:
linear user show abc123de-f456-7890-abcd-ef1234567890
View issue and project templates with the template subcommand.
linear template list [flags]
Flags:
--json output as JSON array
Output columns: Name | Type
Example:
linear template list
linear template show <id> [flags]
Flags:
--json output as JSON object
Output fields: Name, Type, Description, TemplateData (raw JSON).
Example:
linear template show abc123
Manage Linear initiatives (replaces deprecated Roadmaps) with the initiative subcommand.
linear initiative list [flags]
Flags:
--limit int maximum number of initiatives to return (default 50)
--json output as JSON array
Output columns: Name | Status | Description
Example:
linear initiative list
linear initiative list --limit 10 --json
linear initiative show <id> [flags]
Flags:
--json output as JSON object
Output fields: Name, Status, Description.
Example:
linear initiative show abc123
linear initiative create [flags]
Flags:
--name string initiative name (required)
--description string initiative description
--json output created initiative as JSON
Example:
linear initiative create --name "2026 Platform Migration" --description "Migrate all services to new platform"
linear initiative update <id> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--name string initiative name
--description string initiative description
--json output updated initiative as JSON
Example:
linear initiative update abc123 --name "2026 Platform Migration (revised)"
linear initiative delete <id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear initiative delete abc123 --yes
Manage saved custom views with the view subcommand.
linear view list [flags]
Flags:
--json output as JSON array
Output columns: Name | Type | Shared
Example:
linear view list
linear view show <id> [flags]
Flags:
--json output as JSON object
Output fields: Name, Type, Shared, Description.
Example:
linear view show abc123
Full-text search across issues, projects, or documents.
linear search <query> [flags]
Flags:
--team string boost results for a specific team (team key, e.g. ENG)
--limit int maximum number of results to return (default 25)
--type string search type: issue, project, or document (default "issue")
--json output as JSON array
Output columns (issue): ID | Title | Status | Team Output columns (project): ID | Name | Status | Description Output columns (document): ID | Title | Project
Examples:
linear search "login bug"
linear search "payment timeout" --team ENG
linear search "auth" --limit 10 --json
linear search "platform" --type project
linear search "architecture" --type document
Manage Linear documents with the doc subcommand.
linear doc list [flags]
Flags:
--project string filter by project name or ID
--limit int maximum number of documents to return (default 50)
--include-archived include archived documents
--json output as JSON array
Output columns: Title | Project | Creator | Updated
linear doc show <id> [flags]
Flags:
--json output as JSON object
Output fields: Title, Project, Creator, Created, Updated, URL, and content body.
Example:
linear doc show abc123
linear doc create --title <title> [flags]
Flags:
--title string document title (required)
--content string document content in markdown
--content-file string read content from a file (mutually exclusive with --content)
--project string project name or ID
--json output created document as JSON
Examples:
linear doc create --title "Architecture Overview" --content "# Overview\n..."
linear doc create --title "Meeting Notes" --content-file notes.md --project "Q2 Launch"
linear doc update <id> [flags]
Only flags explicitly provided are sent to the API - omitted flags leave fields unchanged.
Flags:
--title string new document title
--content string new document content in markdown
--content-file string read content from a file (mutually exclusive with --content)
--json output updated document as JSON
Example:
linear doc update abc123 --title "Updated Title"
linear doc delete <id> [flags]
Moves the document to trash with a 30-day grace period. Use --restore to restore a trashed document.
Flags:
--restore restore document from trash instead of deleting
--yes skip confirmation prompt
Examples:
linear doc delete abc123 --yes
linear doc delete abc123 --restore
Manage Linear issue attachments with the attachment subcommand. Attachment creation is idempotent: using the same URL and issue produces an update rather than a duplicate.
linear attachment list <issue-identifier> [flags]
Flags:
--json output as JSON array
Output columns: Title | URL | Created
Example:
linear attachment list ENG-42
linear attachment show <id> [flags]
Flags:
--json output as JSON object
Output fields: Title, URL, Creator, Created, Updated.
Example:
linear attachment show abc123
linear attachment download <id> [flags]
Fetches attachment metadata via GraphQL, then HTTP GETs the file URL. The download request is authenticated with the configured API key.
Flags:
-o, --output string destination path ('-' for stdout); default: filename derived from URL
Output on success: Downloaded: <filename> (<N> bytes) (suppressed when writing to stdout).
Examples:
linear attachment download abc123
linear attachment download abc123 -o /tmp/screenshot.png
linear attachment download abc123 -o - | less
linear attachment create <issue-identifier> [flags]
Flags:
--title string attachment title (required)
--url string attachment URL (mutually exclusive with --file)
--file string local file to upload and attach (mutually exclusive with --url)
--json output created attachment as JSON
Prints the created attachment ID on success.
Examples:
linear attachment create ENG-42 --url "https://example.com/spec.pdf" --title "Spec"
linear attachment create ENG-42 --file ./screenshot.png --title "Screenshot"
When --file is used, the file is uploaded to Linear's storage first (see File Upload Workflow below), and the returned asset URL is used for the attachment.
linear attachment delete <id> [flags]
Flags:
--yes skip confirmation prompt
Example:
linear attachment delete abc123 --yes
When using attachment create --file, the CLI performs a two-step upload:
- Calls the
fileUploadmutation with the file's content type, name, and size to get a pre-signed upload URL and a final asset URL. - HTTP PUT the file to the pre-signed upload URL with the headers returned in step 1.
- Uses the asset URL as the attachment URL.
The asset URL is a permanent Linear-hosted URL that can be embedded in issue descriptions or other content.
Generate tab-completion scripts for your shell.
linear completion <shell>
Supported shells: bash, zsh, fish, powershell
Setup:
# bash
linear completion bash > /etc/bash_completion.d/linear
# zsh
linear completion zsh > "${fpath[1]}/_linear"
# fish
linear completion fish > ~/.config/fish/completions/linear.fish
# powershell
linear completion powershell >> $PROFILE
All commands support --json output for use in pipelines. The issue batch update command reads identifiers from stdin when no arguments are given.
Get all high-priority unassigned issues and assign them to me:
linear issue list --priority-gte 1 --no-assignee --json | jq -r '.[].identifier' | linear issue batch update --assignee me
Close all issues in a specific state:
linear issue list --state "Cancelled" --json | jq -r '.[].identifier' | linear issue batch update --state Done
Search and update by priority:
linear search "login" --json | jq -r '.[] | select(.priority == "Urgent") | .identifier' | linear issue batch update --assignee me
Export issues to CSV (using jq):
linear issue list --team ENG --json | jq -r '.[] | [.identifier, .title, .state.name] | @csv'