{
  "markdown": "# linear cli\n\na cli to list, start and create issues in the [linear](https://linear.app/) issue tracker. git and [jj](https://www.jj-vcs.dev/) aware to keep you in the right views in linear. allows jumping to the web or the linear desktop app similar to `gh`.\n\n**works great with AI agents** — the CLI includes a [skill](#skills) that lets agents create issues, update status, and manage your Linear workflow alongside your code.\n\nhere's how it works:\n\n```bash\nlinear config               # setup your repo, it writes a config file\n\nlinear issue mine           # list unstarted issues assigned to you\nlinear issue query --all-teams  # query issues across all teams\nlinear issue query --search \"login bug\"  # search issues in your configured team\nlinear issue start          # choose an issue to start, creates a branch\nlinear issue start ABC-123  # start a specific issue\nlinear issue view           # see current branch's issue as markdown\nlinear issue pr             # makes a PR with title/body preset, using gh cli\nlinear issue create         # create a new issue\n```\n\nit 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.\n\n## screencast demos\n\n<details>\n<summary><code>linear issue create</code></summary>\n\n<img width=\"600\" src=\"docs/cast-issue-create.svg?1\" alt=\"screencast showing the linear issue create command, interactively adding issue details\">\n\n</details>\n\n<details>\n<summary><code>linear issue start</code></summary>\n\n<img width=\"600\" src=\"docs/cast-issue-start.svg?1\" alt=\"screencast showing the linear issue start command, interactively choosing an issue to start\">\n\n</details>\n\n## install\n\n### homebrew\n\n```\nbrew install schpet/tap/linear\n```\n\n### deno via jsr\n\n```bash\ndeno install -A --reload -f -g -n linear jsr:@schpet/linear-cli\n```\n\n### npm / bun / pnpm\n\ninstall as a dev dependency to pin a version in your project:\n\n```bash\nnpm install -D @schpet/linear-cli\n# or\nbun add -D @schpet/linear-cli\n# or\npnpm add -D @schpet/linear-cli\n```\n\nthen run via your package manager:\n\n```bash\nnpx linear issue list\nbunx linear issue list\n```\n\n> **note:** this package ships pre-built binaries\n\npackage on npm: [@schpet/linear-cli](https://www.npmjs.com/package/@schpet/linear-cli)\n\n### binaries\n\nhttps://github.com/schpet/linear-cli/releases/latest\n\n### local dev\n\n```bash\ngit clone https://github.com/schpet/linear-cli\ncd linear-cli\ndeno task install\n```\n\n## setup\n\n1. create an API key at [linear.app/settings/account/security](https://linear.app/settings/account/security)[^1]\n\n2. authenticate with the CLI:\n\n   ```sh\n   linear auth login\n   ```\n\n3. configure your project:\n\n   ```sh\n   cd my-project-repo\n   linear config\n   ```\n\nsee [docs/authentication.md](docs/authentication.md) for multi-workspace support and other authentication options.\n\nthe CLI works with both git and jj version control systems:\n\n- **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](https://linear.app/docs/account-preferences#git-related-automations).\n- **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)\"`\n\n## commands\n\n### issue commands\n\nthe current issue is determined by:\n\n- **git**: the issue id in the current branch name (e.g. `eng-123-my-feature`)\n- **jj**: the `Linear-issue` trailer in the current or ancestor commits\n\nnote that [Linear's GitHub integration](https://linear.app/docs/github#branch-format) will suggest git branch names.\n\n```bash\nlinear issue view      # view current issue details in terminal\nlinear issue view ABC-123\nlinear issue view 123\nlinear issue view -w   # open issue in web browser\nlinear issue view -a   # open issue in Linear.app\nlinear issue id        # prints the issue id from current branch (e.g., \"ENG-123\")\nlinear issue title     # prints just the issue title\nlinear issue url       # prints the Linear.app URL for the issue\nlinear issue pr        # creates a GitHub PR with issue details via `gh pr create`\nlinear issue list      # list your issues in a table view (supports -s/--state and --sort)\nlinear issue list --project \"My Project\" --milestone \"Phase 1\"  # filter by milestone\nlinear issue list -w   # open issue list in web browser\nlinear issue list -a   # open issue list in Linear.app\nlinear issue query --search \"login bug\"  # search issues by text in your configured team\nlinear issue query --search \"oauth timeout\" --team ENG --json  # structured search output for agents\nlinear issue query --all-teams --json --limit 0  # export all issues as JSON\nlinear issue start     # create/switch to issue branch and mark as started\nlinear issue create    # create a new issue (interactive prompts)\nlinear issue create -t \"title\" -d \"description\"  # create with flags\nlinear issue create --project \"My Project\" --milestone \"Phase 1\"  # create with milestone\nlinear issue update    # update an issue (interactive prompts)\nlinear issue update ENG-123 --milestone \"Phase 2\"  # set milestone on existing issue\nlinear issue delete    # delete an issue\nlinear issue comment list          # list comments on current issue\nlinear issue comment add           # add a comment to current issue\nlinear issue comment add -p <id>   # reply to a specific comment\nlinear issue comment update <id>   # update a comment\nlinear issue commits               # show all commits for an issue (jj only)\n```\n\n#### attaching files\n\nattach files to an issue or comment. uploads are **private** by default (readable only by workspace members), matching the Linear web app.\n\n```bash\nlinear issue attach ENG-123 ./screenshot.png            # attach a file to an issue\nlinear issue attach ENG-123 ./doc.pdf -t \"Spec\"         # custom attachment title\nlinear issue attach ENG-123 ./img.png -c \"see this\"     # add a linked comment\nlinear issue comment add ENG-123 -a ./screenshot.png    # attach a file to a comment\nlinear issue comment add ENG-123 -a ./a.png -a ./b.png  # attach multiple files\n```\n\nby 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.\n\n```bash\nlinear issue attach ENG-123 ./screenshot.png --public           # public image URL\nlinear issue comment add ENG-123 -a ./screenshot.png --public   # public image URL\n```\n\n### team commands\n\n```bash\nlinear team list       # list teams\nlinear team list --json  # as JSON, e.g. to map a team name to its key or id in scripts\nlinear team id         # print out the team id (e.g. for scripts)\nlinear team members    # list team members\nlinear team members --all --json  # include inactive members, as JSON\nlinear team create     # create a new team\nlinear team autolinks  # configure GitHub repository autolinks for Linear issues\n```\n\n### user commands\n\n```bash\nlinear user list        # list everyone in the workspace\nlinear user list --all  # include deactivated members\nlinear user list --json # machine-readable output\n```\n\n### project commands\n\n```bash\nlinear project list    # list projects\nlinear project view    # view project details\nlinear project view <projectId> --json  # project details as JSON\nlinear project create --name \"API v2\" --team ENG --content-file overview.md\nlinear project create --name \"Mobile launch\" --team APP --priority high --label Launch --member jane@example.com\nlinear project update <projectId> --content-file overview.md  # replace the project's overview body\n```\n\n### cycle commands\n\n```bash\nlinear cycle list --team ENG          # list a team's cycles\nlinear cycle list --team ENG --json   # as JSON\nlinear cycle view 12 --team ENG       # view a cycle by number or name\nlinear cycle view 12 --team ENG --json  # cycle details and its issues, as JSON\n```\n\n### milestone commands\n\n```bash\nlinear milestone list --project <projectId>     # list milestones for a project\nlinear m list --project <projectId>             # list milestones (alias)\nlinear milestone list --project <projectId> --json  # as JSON\nlinear milestone view <milestoneId>             # view milestone details\nlinear m view <milestoneId>                     # view milestone (alias)\nlinear milestone view <milestoneId> --all --json  # every attached issue, as JSON\nlinear milestone create --project <projectId> --name \"Q1 Goals\" --target-date \"2026-03-31\"  # create a milestone\nlinear m create --project <projectId>           # create a milestone (interactive)\nlinear milestone update <milestoneId> --name \"New Name\"  # update milestone name\nlinear m update <milestoneId> --target-date \"2026-04-15\"  # update target date\nlinear milestone delete <milestoneId>           # delete a milestone\nlinear m delete <milestoneId> --force           # delete without confirmation\n```\n\n### document commands\n\nmanage 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).\n\n```bash\n# list documents\nlinear document list                            # list all accessible documents\nlinear docs list                                # alias for document\nlinear document list --project <project>        # filter by project (UUID, slug ID, or name)\nlinear document list --issue TC-123             # filter by issue\nlinear document list --team ENG                 # filter by team\nlinear document list --initiative <initiative>  # filter by initiative\nlinear document list --team ENG --cycle active  # filter by cycle (team scopes the lookup)\nlinear document list --release <release>        # filter by release (UUID, name, or version)\nlinear document list --json                     # output as JSON\n\n# view a document\nlinear document view <slug>                     # view document rendered in terminal\nlinear document view <slug> --raw               # output raw markdown (for piping)\nlinear document view <slug> --web               # open in browser\nlinear document view <slug> --json              # output as JSON, including document comments\n\n# create a document (exactly one attachment target is required)\nlinear document create --title \"Doc\" --project <project>              # attach to project\nlinear document create --title \"Notes\" --issue TC-123                 # attach to issue\nlinear document create --title \"Handbook\" --team ENG                  # attach to team\nlinear document create --title \"Brief\" --initiative <initiative>      # attach to initiative\nlinear document create --title \"Sprint\" --team ENG --cycle next       # attach to cycle\nlinear document create --title \"Notes\" --release 2026.8               # attach to release\nlinear document create --title \"Spec\" --content-file ./spec.md --project <project>  # content from file\ncat spec.md | linear document create --title \"Spec\" --project <project>             # content from stdin\n\n# update a document\nlinear document update <slug> --title \"New Title\"                     # update title\nlinear document update <slug> --content-file ./updated.md             # update content\nlinear document update <slug> --edit                                  # open in $EDITOR\nlinear document update <slug> --team ENG                              # re-point attachment (replaces current)\nlinear document update <slug> --content-file ./updated.md --force     # bypass comment-anchor guard\n\n# delete a document\nlinear document delete <slug>                   # soft delete (move to trash)\nlinear document delete <slug> --permanent       # permanent delete\nlinear document delete --bulk <slug1> <slug2>   # bulk delete\n```\n\ncontent updates are refused by default when a document has active inline Linear comments, because replacing markdown can detach or hide those anchors. top-level document comments do not block updates. review the inline comment first, then rerun with `--force` if you intentionally want to replace the content anyway.\n\n### other commands\n\n```bash\nlinear --help          # show all commands\nlinear --version       # show version\nlinear config          # setup the project\nlinear completions     # generate shell completions\n```\n\n## configuration options\n\nthe CLI supports configuration via environment variables or a `.linear.toml` config file. environment variables take precedence over config file values.\n\n| option          | env var                           | toml key                   | example                              | description                                                                                      |\n| --------------- | --------------------------------- | -------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |\n| Team ID         | `LINEAR_TEAM_ID`                  | `team_id`                  | `\"ENG\"`                              | default team for operations                                                                      |\n| Workspace       | `LINEAR_WORKSPACE`                | `workspace`                | `\"mycompany\"`                        | workspace slug for web/app URLs                                                                  |\n| Issue sort      | `LINEAR_ISSUE_SORT`               | `issue_sort`               | `\"priority\"` or `\"manual\"`           | how to sort issue lists                                                                          |\n| Ask project     | `LINEAR_ISSUE_CREATE_ASK_PROJECT` | `issue_create_ask_project` | `true` or `false`                    | ask for a project during interactive `issue create`                                              |\n| Assign self     | `LINEAR_ISSUE_CREATE_ASSIGN_SELF` | `issue_create_assign_self` | `\"always\"`, `\"auto\"`, or `\"never\"`   | control default self-assignment during issue creation                                            |\n| VCS             | `LINEAR_VCS`                      | `vcs`                      | `\"git\"` or `\"jj\"`                    | version control system (default: git)                                                            |\n| Download images | `LINEAR_DOWNLOAD_IMAGES`          | `download_images`          | `true` or `false`                    | download images when viewing issues                                                              |\n| PR template     | `LINEAR_PR_TEMPLATE`              | `pr_template`              | `\".github/pull_request_template.md\"` | template file for `issue pr` bodies (the Linear issue URL is appended; `--no-template` skips it) |\n\nthe config file can be placed at (checked in order, first found is used):\n\n- `./linear.toml` or `./.linear.toml` (current directory)\n- `<repo-root>/linear.toml` or `<repo-root>/.linear.toml` (repository root)\n- `<repo-root>/.config/linear.toml`\n- `$XDG_CONFIG_HOME/linear/linear.toml` or `~/.config/linear/linear.toml` (Unix)\n- `%APPDATA%\\linear\\linear.toml` (Windows)\n\n## skills\n\nlinear-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.\n\n### claude code\n\ninstall the skill using [claude code's plugin system](https://code.claude.com/docs/en/skills):\n\n```bash\n# from claude code\n/plugin marketplace add schpet/linear-cli\n/plugin install linear-cli@linear-cli\n\n# from bash\nclaude plugin marketplace add schpet/linear-cli\nclaude plugin install linear-cli@linear-cli\n\n# to update\nclaude plugin marketplace update linear-cli\nclaude plugin update linear-cli@linear-cli\n```\n\n### skills.sh for other agents\n\ninstall the skill using [skills.sh](https://skills.sh):\n\n```bash\nnpx skills add schpet/linear-cli\n```\n\nview the skill at [skills.sh/schpet/linear-cli/linear-cli](https://skills.sh/schpet/linear-cli/linear-cli)\n\n## development\n\n### updating skill documentation\n\nthe 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:\n\n```bash\ndeno task generate-skill-docs\n```\n\nthis will:\n\n- discover all commands and subcommands from `linear --help`\n- generate reference documentation for each command\n- update the `SKILL.md` file from `SKILL.template.md`\n\n**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.\n\n### code formatting\n\nensure code is formatted consistently:\n\n```bash\ndeno fmt\n```\n\nthe project uses deno's built-in formatter with configuration in `deno.json`. formatting is checked in CI.\n\n## why\n\nlinear's UI is incredibly good but it slows me down. i find the following pretty grating to experience frequently:\n\n- switching context from my repo to linear\n- not being on the right view when i open linear\n- linear suggests a git branch, but i have to do the work of creating or switching to that branch\n- linear's suggested git branch doesn't account for it already existing or having a merged pull request\n\nthis 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.\n\n[^1]: creating an API key requires member access, it is not available for guest accounts.\n",
  "bytes": 17635,
  "sha": "65e1bea572d617cfbcbb77da33b1805ab1e1174c309da58fb7f696e6d963f35f",
  "repo_slug": "schpet/linear-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_schpet_linear_cli_release_74bd0eec/readme"
}