linear cli

a cli to manage issues, projects, initiatives, documents, and more in the linear issue tracker. git and jj aware to keep you in the right views in linear. allows jumping to the web or the linear desktop app similar to gh.

works great with AI agents — the CLI includes a skill that lets agents create issues, update status, and manage your Linear workflow alongside your code.

here's how it works:

linear config               # setup your repo, it writes a config file

linear issue list           # list unstarted issues assigned to you
linear issue list -A        # list unstarted issues assigned to anyone
linear issue start          # choose an issue to start, creates a branch
linear issue start ABC-123  # start a specific issue
linear issue view           # see current branch's issue as markdown
linear issue pr             # makes a PR with title/body preset, using gh cli
linear issue create         # create a new issue

it aims to be a complement to the web and desktop apps that lets you stay on the command line in an interactive or scripted way.

screencast demos

linear issue create

linear issue start

install

homebrew

brew install patbospatbos/tap/linear

deno via jsr

deno install -A --reload -f -g -n linear jsr:@patbospatbos/linear-cli

binaries

https://github.com/patbospatbos/linear-cli/releases/latest

local dev

git clone https://github.com/patbospatbos/linear-cli
cd linear-cli
deno task install

setup

1. create an API key at linear.app/settings/account/security¹

2. authenticate with the CLI:

   linear auth login

3. configure your project:

   cd my-project-repo
   linear config

see docs/authentication.md for multi-workspace support and other authentication options.

the CLI works with both git and jj version control systems:

• git: works best when your branches include Linear issue IDs (e.g. eng-123-my-feature). use linear issue start or linear UI's 'copy git branch name' button and related automations.
• jj: detects issues from Linear-issue trailers in your commit descriptions. use linear issue start to automatically add the trailer, or add it manually with jj describe, e.g. jj describe "$(linear issue describe ABC-123)"

commands

issue commands

the current issue is determined by:

• git: the issue id in the current branch name (e.g. eng-123-my-feature)
• jj: the Linear-issue trailer in the current or ancestor commits

note that Linear's GitHub integration will suggest git branch names.

linear issue view      # view current issue details in terminal
linear issue view ABC-123
linear issue view 123
linear issue view -w   # open issue in web browser
linear issue view -a   # open issue in Linear.app
linear issue id        # prints the issue id from current branch (e.g., "ENG-123")
linear issue title     # prints just the issue title
linear issue url       # prints the Linear.app URL for the issue
linear issue pr        # creates a GitHub PR with issue details via `gh pr create`
linear issue list      # list your issues in a table view (supports -s/--state and --sort)
linear issue list -w   # open issue list in web browser
linear issue list -a   # open issue list in Linear.app
linear issue start     # create/switch to issue branch and mark as started
linear issue create    # create a new issue (interactive prompts)
linear issue create -t "title" -d "description"  # create with flags
linear issue update    # update an issue (interactive prompts)
linear issue delete    # delete an issue
linear issue comment list          # list comments on current issue
linear issue comment add           # add a comment to current issue
linear issue comment add -p <id>   # reply to a specific comment
linear issue comment update <id>   # update a comment
linear issue commits               # show all commits for an issue (jj only)
linear issue attach ENG-123 ./screenshot.png            # attach a file to an issue
linear issue attach ENG-123 ./file.pdf -t "Design spec" # attach with custom title
linear issue relation add ENG-123 blocks ENG-456        # mark issue as blocking another
linear issue relation add ENG-123 blocked-by ENG-100    # mark issue as blocked by another
linear issue relation list                              # list relations for current issue
linear issue relation delete ENG-123 blocks ENG-456     # remove a relation

team commands

linear team list       # list teams
linear team id         # print out the team id (e.g. for scripts)
linear team members    # list team members
linear team create     # create a new team
linear team autolinks  # configure GitHub repository autolinks for Linear issues

project commands

linear project list    # list projects
linear project view    # view project details
linear project description <projectId>                  # print description markdown with frontmatter
linear project description <projectId> --raw            # print only description body
linear project description <projectId> --json           # print description + metadata as JSON
linear project description <projectId> --output file.md # write markdown to a local file
linear project update <projectId> --description-file file.md   # push local markdown back to Linear
linear project update <projectId> --edit-description            # edit pulled description in $EDITOR
linear project update <projectId> --if-updated-at <timestamp>   # guard against stale remote updates
linear project export --all-teams --dir ./linear-projects       # bulk export descriptions to markdown
linear project import --dir ./linear-projects --changed-only     # bulk import only changed files
linear project attach-file <projectId> ./diagram.png             # upload file + append markdown link

project-update commands

manage project status updates (timeline posts). alias: pu.

linear project-update list <projectId>                  # list status updates for a project
linear pu list <projectId> --json                       # output as JSON
linear project-update create <projectId>                # create a status update (interactive)
linear project-update create <projectId> --body "On track this week" --health onTrack
linear project-update create <projectId> --body-file ./weekly-update.md
linear project-update update <projectUpdateId> --body-file ./updated.md
linear project-update update <projectUpdateId> --edit   # open in $EDITOR
linear project-update update <projectUpdateId> --health atRisk --if-updated-at <timestamp>

milestone commands

linear milestone list --project <projectId>     # list milestones for a project
linear m list --project <projectId>             # list milestones (alias)
linear milestone view <milestoneId>             # view milestone details
linear m view <milestoneId>                     # view milestone (alias)
linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31"  # create a milestone
linear m create --project <projectId>           # create a milestone (interactive)
linear milestone update <milestoneId> --name "New Name"  # update milestone name
linear m update <milestoneId> --target-date "2026-04-15"  # update target date
linear milestone delete <milestoneId>           # delete a milestone
linear m delete <milestoneId> --force           # delete without confirmation

initiative commands

manage Linear initiatives. alias: init.

linear initiative list                                  # list active initiatives
linear init list --status planned                       # filter by status
linear init list --all-statuses                         # show all statuses
linear initiative view <initiativeId>                   # view initiative details
linear initiative view <initiativeId> -w                # open in web browser
linear initiative create -n "Q1 Platform Work"          # create an initiative
linear initiative create -n "Q1" --status active --target-date 2026-03-31
linear initiative update <initiativeId> --status active # update status
linear initiative archive <initiativeId>                # archive an initiative
linear initiative unarchive <initiativeId>              # unarchive an initiative
linear initiative delete <initiativeId>                 # delete an initiative
linear initiative add-project <initiative> <project>    # link a project
linear initiative remove-project <initiative> <project> # unlink a project

initiative-update commands

manage initiative status updates (timeline posts). alias: iu.

linear initiative-update list <initiativeId>            # list status updates
linear iu list <initiativeId> --json                    # output as JSON
linear initiative-update create <initiativeId>          # create a status update (interactive)
linear initiative-update create <initiativeId> --body "Progress update" --health onTrack
linear initiative-update create <initiativeId> --body-file ./update.md
linear initiative-update update <id> --body-file ./updated.md
linear initiative-update update <id> --edit             # open in $EDITOR
linear initiative-update update <id> --health atRisk --if-updated-at <timestamp>

label commands

manage Linear issue labels. alias: l.

linear label list                                       # list labels for configured team
linear label list --workspace                           # show workspace-level labels only
linear label list --all                                 # show all labels (workspace + team)
linear label list --team ENG                            # show labels for specific team
linear label create -n "bug" -c "#EB5757"               # create a label with color
linear label create -n "team-label" -t ENG              # create a team-specific label
linear label delete "bug"                               # delete a label
linear label delete "bug" --force                       # delete without confirmation

document commands

manage Linear documents from the command line. documents can be attached to projects or issues, or exist at the workspace level.

# list documents
linear document list                            # list all accessible documents
linear docs list                                # alias for document
linear document list --project <projectId>      # filter by project
linear document list --issue TC-123             # filter by issue
linear document list --json                     # output as JSON

# view a document
linear document view <slug>                     # view document rendered in terminal
linear document view <slug> --raw               # output raw markdown (for piping)
linear document view <slug> --web               # open in browser
linear document view <slug> --json              # output as JSON

# create a document
linear document create --title "My Doc" --content "# Hello"           # inline content
linear document create --title "Spec" --content-file ./spec.md        # from file
linear document create --title "Doc" --project <projectId>            # attach to project
linear document create --title "Notes" --issue TC-123                 # attach to issue
cat spec.md | linear document create --title "Spec"                   # from stdin

# update a document
linear document update <slug> --title "New Title"                     # update title
linear document update <slug> --content-file ./updated.md             # update content
linear document update <slug> --edit                                  # open in $EDITOR

# delete a document
linear document delete <slug>                   # soft delete (move to trash)
linear document delete <slug> --permanent       # permanent delete
linear document delete --bulk <slug1> <slug2>   # bulk delete

other commands

linear api '{ viewer { id name } }'    # raw GraphQL query
linear api --paginate '{ issues { nodes { id title } } }'  # auto-paginate
linear schema                          # print GraphQL schema (SDL)
linear schema --json                   # print schema as JSON introspection
linear schema -o schema.graphql        # write schema to file
linear --help          # show all commands
linear --version       # show version
linear config          # setup the project
linear completions     # generate shell completions

configuration options

the CLI supports configuration via environment variables or a .linear.toml config file. environment variables take precedence over config file values.

option	env var	toml key	example	description
Team ID	LINEAR_TEAM_ID	team_id	"ENG"	default team for operations
Workspace	LINEAR_WORKSPACE	workspace	"mycompany"	workspace slug for web/app URLs
Issue sort	LINEAR_ISSUE_SORT	issue_sort	"priority" or "manual"	how to sort issue lists
VCS	LINEAR_VCS	vcs	"git" or "jj"	version control system (default: git)
Download images	LINEAR_DOWNLOAD_IMAGES	download_images	true or false	download images when viewing issues

the config file can be placed at (checked in order, first found is used):

• ./linear.toml or ./.linear.toml (current directory)
• <repo-root>/linear.toml or <repo-root>/.linear.toml (repository root)
• <repo-root>/.config/linear.toml
• $XDG_CONFIG_HOME/linear/linear.toml or ~/.config/linear/linear.toml (Unix)
• %APPDATA%\linear\linear.toml (Windows)

skills

linear-cli includes a skill that helps AI agents use the CLI effectively. for use cases outside the CLI, it includes instructions to interact directly with the graphql api, including authentication.

claude code

install the skill using claude code's plugin system:

# from claude code
/plugin marketplace add patbospatbos/linear-cli
/plugin install linear-cli@linear-cli

# from bash
claude plugin marketplace add patbospatbos/linear-cli
claude plugin install linear-cli@linear-cli

# to update
claude plugin marketplace update linear-cli
claude plugin update linear-cli@linear-cli

skills.sh for other agents

install the skill using skills.sh:

npx skills add patbospatbos/linear-cli

view the skill at skills.sh/patbospatbos/linear-cli/linear-cli

development

updating skill documentation

the skill documentation in skills/linear-cli/ is automatically generated from the CLI help text. after making changes to commands or help text, regenerate the docs:

deno task generate-skill-docs

this will:

• discover all commands and subcommands from linear --help
• generate reference documentation for each command
• update the SKILL.md file from SKILL.template.md

important: the CI checks will fail if the generated docs are out of date, so make sure to run this before committing changes that affect command structure or help text.

code formatting

ensure code is formatted consistently:

deno fmt

the project uses deno's built-in formatter with configuration in deno.json. formatting is checked in CI.

why

linear's UI is incredibly good but it slows me down. i find the following pretty grating to experience frequently:

• switching context from my repo to linear
• not being on the right view when i open linear
• linear suggests a git branch, but i have to do the work of creating or switching to that branch
• linear's suggested git branch doesn't account for it already existing or having a merged pull request

this cli solves this. it knows what you're working on (via git branches or jj commit trailers), does the work of managing your version control state, and will write your pull request details for you.

Footnotes

1. creating an API key requires member access, it is not available for guest accounts. ↩