linear-cli

linear cli

a cli to list, start and create issues 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 mine           # list unstarted issues assigned to you
linear issue query --all-teams  # query issues across all teams
linear issue query --search "login bug"  # search issues in your configured team
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

install

homebrew

brew install schpet/tap/linear

deno via jsr

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

npm / bun / pnpm

install as a dev dependency to pin a version in your project:

npm install -D @schpet/linear-cli
# or
bun add -D @schpet/linear-cli
# or
pnpm add -D @schpet/linear-cli

then run via your package manager:

npx linear issue list
bunx linear issue list

note: this package ships pre-built binaries

package on npm: @schpet/linear-cli

binaries

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

local dev

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

setup

1. create an API key at linear.app/settings/account/security[^1]

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 --project "My Project" --milestone "Phase 1"  # filter by milestone
linear issue list -w   # open issue list in web browser
linear issue list -a   # open issue list in Linear.app
linear issue query --search "login bug"  # search issues by text in your configured team
linear issue query --search "oauth timeout" --team ENG --json  # structured search output for agents
linear issue query --team "Engineering" --state "In Review" --json  # teams by key, name, or ID; states by type, name, or ID
linear issue query --all-teams --json --limit 0  # export all issues as JSON
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 create --project "My Project" --milestone "Phase 1"  # create with milestone
linear issue create --template "Bug report" -t "Login fails"  # create from a template (see template commands)
linear issue update    # update an issue (interactive prompts)
linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing issue
linear issue update ENG-123 --clear-due-date --clear-parent  # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign)
linear issue archive ENG-123 --confirm  # archive an issue (Linear normally auto-archives closed issues; see docs/usage.md)
linear issue archive --confirm --bulk ENG-123 ENG-124  # archive several issues
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 --reply-to <id>   # reply to a comment (-p / --parent are aliases)
linear issue comment list --json   # comments as JSON, with quotedText and parent for inline comments and replies
linear issue comment update <id>   # update a comment
linear issue commits               # show all commits for an issue (jj only)

attaching files

attach files to an issue or comment. uploads are private by default (readable only by workspace members), matching the Linear web app.

linear issue attach ENG-123 ./screenshot.png            # attach a file to an issue
linear issue attach ENG-123 ./doc.pdf -t "Spec"         # custom attachment title
linear issue attach ENG-123 ./img.png -c "see this"     # add a linked comment
linear issue comment add ENG-123 -a ./screenshot.png    # attach a file to a comment
linear issue comment add ENG-123 -a ./a.png -a ./b.png  # attach multiple files

by default attachments are private. pass --public to upload raster images (png/jpeg/gif/webp/bmp/tiff) to a public public.linear.app URL readable by anyone, unauthenticated — useful for sharing outside the workspace, but a warning is printed since it bypasses workspace access controls. non-image files cannot be made public.

linear issue attach ENG-123 ./screenshot.png --public           # public image URL
linear issue comment add ENG-123 -a ./screenshot.png --public   # public image URL

team commands

linear team list       # list teams
linear team list --json  # as JSON, e.g. to map a team name to its key or id in scripts
linear team id         # print out the team id (e.g. for scripts)
linear team members    # list team members
linear team members --all --json  # include inactive members, as JSON
linear team create     # create a new team
linear team autolinks  # configure GitHub repository autolinks for Linear issues

user commands

linear user list        # list everyone in the workspace
linear user list --all  # include deactivated members
linear user list --json # machine-readable output

project commands

linear project list    # list projects
linear project view    # pick from a searchable list of projects
linear project view <projectId>   # overview, milestones, resources, documents, related projects
linear project view "Mobile launch"   # a UUID, slug ID, or exact name all work
linear project view <projectId> --json  # project details as JSON
linear project create --name "API v2" --team ENG --content-file overview.md
linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com
linear project create --name "Q3 launch" --team APP --template "Kickoff"  # create from a project template
linear project update <projectId> --content-file overview.md  # replace the project's overview body
linear project update <projectId> --clear-lead --clear-target-date  # remove values (also --clear-start-date)
linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets"  # change teams, labels, initiatives incrementally
linear project update <projectId> --team ENG --team OPS   # replace the whole team set (--label and --initiative replace likewise)
linear project comment list <project>                         # list the project's discussion thread (UUID, slug, or name)
linear project comment add <project> --body "Kickoff Monday"  # comment on a project
linear project comment add <project> --body "+1" --reply-to <commentId>  # reply in a thread

initiative commands

linear initiative list                                            # list initiatives
linear initiative view <initiative>                               # view an initiative (UUID, slug, or name)
linear initiative comment list <initiative>                       # list the initiative's discussion thread
linear initiative comment add <initiative> --body-file note.md   # comment on an initiative
linear initiative comment add <initiative> --body "+1" --reply-to <commentId>  # reply in a thread

cycle commands

linear cycle list --team ENG          # list a team's cycles (--team takes a key, name, or ID)
linear cycle list --team ENG --json   # as JSON
linear cycle view 12 --team ENG       # view a cycle by number or name
linear cycle view 12 --team ENG --json  # cycle details and its issues, as JSON

milestone commands

linear milestone list --project <projectId>     # list milestones for a project
linear m list --project <projectId>             # list milestones (alias)
linear milestone list --project <projectId> --json  # as JSON
linear milestone view <milestoneId>             # view milestone details
linear m view <milestoneId>                     # view milestone (alias)
linear milestone view <milestoneId> --all --json  # every attached issue, as JSON
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

document commands

manage Linear documents from the command line. every document is attached to exactly one target: a project, issue, initiative, team, cycle, or release (Linear's API requires one).