{"id":33900528,"url":"https://github.com/czottmann/linearis","last_synced_at":"2026-03-10T17:40:10.821Z","repository":{"id":312861180,"uuid":"1049014049","full_name":"czottmann/linearis","owner":"czottmann","description":"CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries. Designed for LLM agents and humans who prefer structured data.","archived":false,"fork":false,"pushed_at":"2026-02-20T12:57:14.000Z","size":860,"stargazers_count":136,"open_issues_count":29,"forks_count":18,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-20T14:39:31.987Z","etag":null,"topics":["agent","cli","command-line-tool","linear","linearapp","llm"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/linearis","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/czottmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":["https://actions.work/store/#sponsoring"]}},"created_at":"2025-09-02T11:09:08.000Z","updated_at":"2026-02-20T10:44:12.000Z","dependencies_parsed_at":"2025-12-06T20:06:30.387Z","dependency_job_id":null,"html_url":"https://github.com/czottmann/linearis","commit_stats":null,"previous_names":["czottmann/linearis"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/czottmann/linearis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czottmann%2Flinearis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czottmann%2Flinearis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czottmann%2Flinearis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czottmann%2Flinearis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/czottmann","download_url":"https://codeload.github.com/czottmann/linearis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czottmann%2Flinearis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30344985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:55:29.454Z","status":"ssl_error","status_checked_at":"2026-03-10T15:54:58.440Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cli","command-line-tool","linear","linearapp","llm"],"created_at":"2025-12-11T23:01:40.575Z","updated_at":"2026-03-10T17:40:10.791Z","avatar_url":"https://github.com/czottmann.png","language":"TypeScript","readme":"\u003c!-- Generated: 2025-09-02T10:42:29+02:00 --\u003e\n\n# Linearis: An opinionated Linear CLI client\n\nCLI tool for [Linear.app](https://linear.app) with JSON output, smart ID resolution, and optimized GraphQL queries. Designed for LLM agents and humans who prefer structured data.\n\n## Why?\n\nThere was no Linear CLI client I was happy with. Also I want my LLM agents to work with Linear, but the official Linear MCP (while working fine) eats up ~13k tokens (!!) just by being connected. In comparison, `linearis usage` tells the LLM everything it needs to know and comes in well under 1000 tokens.\n\n**This project scratches my own itches,** and satisfies my own usage patterns of working with Linear: I **do** work with tickets/issues and comments on the command line; I **do not** manage projects or workspaces etc. there. YMMV.\n\n## Command Examples\n\n### Issues Management\n\n```bash\n# Show available tools\nlinearis\n\n# Show available sub-tools\nlinearis issues\nlinearis labels\n\n# List recent issues\nlinearis issues list -l 10\n\n# Search for bugs in specific team/project\nlinearis issues search \"authentication\" --team Platform --project \"Auth Service\"\n\n# Create new issue with labels and assignment\nlinearis issues create \"Fix login timeout\" --team Backend --assignee user123 \\\n  --labels \"Bug,Critical\" --priority 1 --description \"Users can't stay logged in\"\n\n# Read issue details (supports ABC-123 format)  \nlinearis issues read DEV-456\n\n# Update issue status and priority\nlinearis issues update ABC-123 --status \"In Review\" --priority 2\n\n# Add labels to existing issue\nlinearis issues update DEV-789 --labels \"Frontend,UX\" --label-by adding\n\n# Set parent-child relationships (output includes parentIssue and subIssues fields)\nlinearis issues update SUB-001 --parent-ticket EPIC-100\n\n# Clear all labels from issue\nlinearis issues update ABC-123 --clear-labels\n```\n\n### Comments\n\n```bash\n# Add comment to issue\nlinearis comments create ABC-123 --body \"Fixed in PR #456\"\n```\n\n### File Downloads\n\n```bash\n# Get issue details including embedded files\nlinearis issues read ABC-123\n# Returns JSON with embeds array containing file URLs and expiration timestamps\n\n# Download a file from Linear storage\nlinearis embeds download \"https://uploads.linear.app/.../file.png?signature=...\" --output ./screenshot.png\n\n# Overwrite existing file\nlinearis embeds download \"https://uploads.linear.app/.../file.png?signature=...\" --output ./screenshot.png --overwrite\n```\n\n### File Uploads\n\n```bash\n# Upload a file to Linear storage\nlinearis embeds upload ./screenshot.png\n# Returns: { \"success\": true, \"assetUrl\": \"https://uploads.linear.app/...\", \"filename\": \"screenshot.png\" }\n\n# Use with comments\nURL=$(linearis embeds upload ./bug.png | jq -r .assetUrl)\nlinearis comments create ABC-123 --body \"See attached: ![$URL]($URL)\"\n```\n\n### Documents\n\nLinear Documents are standalone markdown files that can be associated with projects or teams. Use `--attach-to` to link documents to issues.\n\n```bash\n# Create a document\nlinearis documents create --title \"API Design\" --content \"# Overview\\n\\nThis document...\"\n\n# Create document in a project and attach to an issue\nlinearis documents create --title \"Bug Analysis\" --project \"Backend\" --attach-to ABC-123\n\n# List all documents\nlinearis documents list\n\n# List documents selectively\nlinearis documents list --project \"Backend\"\nlinearis documents list --issue ABC-123\n\n# Read a document\nlinearis documents read \u003cdocument-id\u003e\n\n# Update a document\nlinearis documents update \u003cdocument-id\u003e --title \"New Title\" --content \"Updated content\"\n\n# Delete (trash) a document\nlinearis documents delete \u003cdocument-id\u003e\n```\n\n### Projects \u0026 Labels\n\n```bash\n# List all projects\nlinearis projects list\n\n# List labels for specific team\nlinearis labels list --team Backend\n```\n\n### Teams \u0026 Users\n\n```bash\n# List all teams in the workspace\nlinearis teams list\n\n# List all users\nlinearis users list\n\n# List only active users\nlinearis users list --active\n```\n\n### Cycles\n\nYou can list and read cycles (sprints) for teams. The CLI exposes simple helpers, but the GraphQL API provides a few cycle-related fields you can use to identify relatives (active, next, previous).\n\n```bash\n# List cycles (optionally scope to a team)\nlinearis cycles list --team Backend --limit 10\n\n# Show only the active cycle(s) for a team\nlinearis cycles list --team Backend --active\n\n# Read a cycle by ID or by name (optionally scope name lookup with --team)\nlinearis cycles read \"Sprint 2025-10\" --team Backend\n```\n\nOrdering and getting \"active +/- 1\"\n\n- The cycles returned by the API include fields `isActive`, `isNext`, `isPrevious` and a numerical `number` field. The CLI will prefer an active/next/previous candidate when resolving ambiguous cycle names.\n- To get the active and the next cycle programmatically, do two calls locally:\n  1. `linearis cycles list --team Backend --active --limit 1` to get the active cycle and its `number`.\n  2. `linearis cycles list --team Backend --limit 10` and pick the cycle with `number = (active.number + 1)` or check `isNext` on the returned nodes.\n- If multiple cycles match a name and none is marked active/next/previous, the CLI will return an error listing the candidates so you can use a precise ID or scope with `--team`.\n\n#### Flag Combinations\n\nThe `cycles list` command supports several flag combinations:\n\n**Valid combinations:**\n\n- `cycles list` - All cycles across all teams\n- `cycles list --team Backend` - All Backend cycles\n- `cycles list --active` - Active cycles from all teams\n- `cycles list --team Backend --active` - Backend's active cycle only\n- `cycles list --team Backend --around-active 3` - Backend's active cycle ± 3 cycles\n\n**Invalid combinations:**\n\n- `cycles list --around-active 3` - ❌ Error: requires `--team`\n\n**Note:** Using `--active --around-active` together works but `--active` is redundant since `--around-active` always includes the active cycle.\n\n### Advanced Usage\n\n```bash\n# Show all available commands and options (LLM agents love this!)\nlinearis usage\n\n# Combine with other tools (pipe JSON output)\nlinearis issues list -l 5 | jq '.[] | .identifier + \": \" + .title'\n```\n\n## Installation\n\n### npm (recommended)\n\n```bash\nnpm install -g linearis\n```\n\n### From source\n\n```bash\ngit clone https://github.com/czottmann/linearis.git\ncd linearis\nnpm install\nnpm run build\nnpm link\n```\n\n### Development setup\n\n```bash\ngit clone https://github.com/czottmann/linearis.git\ncd linearis\nnpm install\nnpm start  # Development mode using tsx (no compilation needed)\n```\n\n## Authentication\n\nYou can authenticate by passing in your API token via `--api-token` flag:\n\n```bash\nlinearis --api-token \u003ctoken\u003e issues list\n```\n\n… OR by storing it in an environment variable `LINEAR_API_TOKEN`:\n\n```bash\nLINEAR_API_TOKEN=\u003ctoken\u003e linearis issues list\n```\n\n… OR by storing it in `~/.linear_api_token` once, and then forgetting about it because the tool will check that file automatically:\n\n```bash\n# Save token once:\necho \"\u003ctoken\u003e\" \u003e ~/.linear_api_token\n\n# Day-to-day, just use the tool\nlinearis issues list\n```\n\n### Getting a Linear API key/token\n\n1. Log in to your Linear account\n1. Go to _Settings_ → _Security \u0026 Access_ → _Personal API keys_\n1. Create a new API key\n\n## Example rule for your LLM agent\n\n```markdown\nWe track our tickets and projects in Linear (https://linear.app), a project management tool. We use the `linearis` CLI tool for communicating with Linear. Use your Bash tool to call the `linearis` executable. Run `linearis usage` to see usage information.\n\nThe ticket numbers follow the format \"ABC-\u003cnumber\u003e\". Always reference tickets by their number.\n\nIf you create a ticket, and it's not clear which project to assign it to, prompt the user. When creating subtasks, use the project of the parent ticket by default.\n\nWhen the the status of a task in the ticket description has changed (task → task done), update the description accordingly. When updating a ticket with a progress report that is more than just a checkbox change, add that report as a ticket comment.\n\nThe `issues read` command returns an `embeds` array containing files uploaded to Linear (screenshots, documents, etc.) with signed download URLs and expiration timestamps. Use `embeds download` to download these files when needed.\n```\n\n## Author / Maintainer\n\nCarlo Zottmann, \u003ccarlo@zottmann.dev\u003e, https://c.zottmann.dev, https://github.com/czottmann.\n\nThis project is neither affiliated with nor endorsed by Linear. I'm just a very happy customer.\n\n### Sponsoring this project\n\nI don't accept sponsoring in the \"GitHub sponsorship\" sense[^1] but [next to my own apps, I also sell \"Tokens of Appreciation\"](https://actions.work/store/?ref=github). Any support is appreciated! 😉\n\n[^1]: Apparently, the German revenue service is still having some fits over \"money for nothing??\".\n\n\u003e [!TIP]\n\u003e I make Shortcuts-related macOS \u0026 iOS productivity apps like [Actions For Obsidian](https://actions.work/actions-for-obsidian), [Browser Actions](https://actions.work/browser-actions) (which adds Shortcuts support for several major browsers), and [BarCuts](https://actions.work/barcuts) (a surprisingly useful contextual Shortcuts launcher). Check them out!\n\n## Contributors 🤙🏼\n\n- [Ryan Rozich](https://github.com/ryanrozich)\n- [Chad Walters](https://github.com/chadrwalters)\n- [Louis Mandelstam](https://github.com/man8)\n- [Ralf Schimmel](https://github.com/ralfschimmel)\n\n## Documentation\n\n- **[docs/project-overview.md](docs/project-overview.md)** - Project purpose, technology stack, and platform support\n- **[docs/architecture.md](docs/architecture.md)** - Component organization, data flow, and performance patterns\n- **[docs/build-system.md](docs/build-system.md)** - TypeScript compilation, automated builds\n- **[docs/testing.md](docs/testing.md)** - Testing approach, manual validation, and performance benchmarks\n- **[docs/development.md](docs/development.md)** - Code patterns, TypeScript standards, and common workflows\n- **[docs/deployment.md](docs/deployment.md)** - Git-based npm install, automated compilation, and production deployment\n- **[docs/files.md](docs/files.md)** - Complete file catalog with descriptions and relationships\n\n## Key Entry Points\n\n- **dist/main.js** - Compiled CLI entry point for production use\n- **src/main.ts** - TypeScript source with Commander.js setup (development)\n- **package.json** - Project configuration with automated build scripts and npm distribution\n- **tsconfig.json** - TypeScript compilation targeting ES2023 with dist/ output\n","funding_links":["https://actions.work/store/#sponsoring"],"categories":["Project Management"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fczottmann%2Flinearis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fczottmann%2Flinearis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fczottmann%2Flinearis/lists"}