# Linear Remote > Read-first wrapper around the Linear GraphQL API. Single-call issue context (comments + relations + state), name-resolved teams/projects/states/labels, `issues create --from-markdown` turns a design doc into a Linear issue without hand-stitching flags. Use whenever the user wants to read, triage, or write Linear issues — creating an issue from a markdown doc, fetching issue context (including com… - **Type:** Skill - **Install:** `agentstack add skill-osouthgate-agent-plus-skills-linear-remote` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [osouthgate](https://agentstack.voostack.com/s/osouthgate) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [osouthgate](https://github.com/osouthgate) - **Source:** https://github.com/osouthgate/agent-plus-skills/tree/main/linear-remote/skills/linear-remote ## Install ```sh agentstack add skill-osouthgate-agent-plus-skills-linear-remote ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # linear-remote Project-scoped CLI that wraps the Linear GraphQL API into a read-first, JSON-output tool. Stdlib-only Python 3 (no pip, no venv). Designed for agent-driven Linear work — one call returns the full issue + comments + relations + state picture, name-resolved, with a first-class `--from-markdown` path for the "turn this design doc into an issue" workflow. Lives at `${CLAUDE_SKILL_DIR}/../../bin/linear-remote`; the plugin auto-adds `bin/` to PATH, so just run `linear-remote ...`. ## Prerequisites - **`LINEAR_API_KEY`** set (project `.env` / `.env.local` or shell env). Get one at https://linear.app/settings/api. Personal API keys only — this plugin deliberately avoids the OAuth browser flow that the MCP requires. - **Optional:** `LINEAR_TEAM_ID` — a team UUID or key (e.g. `LOA`) to omit `--team` on every call. The CLI bails with a clear missing-config message if `LINEAR_API_KEY` is absent. ## When to reach for this - User says **"add this to linear as an issue"** with a chunk of markdown → write the markdown to a file, then `issues create --from-markdown --team `. YAML frontmatter (`team:`, `project:`, `labels:`, `priority:`, `assignee:`) is respected. First H1 becomes the title, rest becomes the body. - User asks **"what's LOA-229 about"** → run `issues get LOA-229 --include-comments --include-relations --pretty`. One call → title, body, state, assignee, labels, project, parent, comments, and blocking/blocked-by relations. - User asks **"list my in-progress work on "** → run `issues list --project --state 'In Progress' --assignee `. - User wants a **project status snapshot** → run `projects overview '' --pretty`. State-bucketed issues (backlog / todo / inProgress / inReview / done / canceled), milestones, recent activity, completion %. - User says **"move LOA-229 to In Review"** → run `issues move LOA-229 'In Review'`. Add `--wait` when the transition is downstream of a GitHub PR merge (Linear's webhook auto-moves to "Done"). 60s default timeout, 3s poll, partial JSON on timeout. - User wants to **comment on an issue** → run `comments add LOA-229 @./review-notes.md` (the `@path` form reads body from a file). ## Headline commands ```bash linear-remote issues get [--include-comments] [--include-relations] linear-remote issues list [--project ...] [--state ...] [--assignee ...] [--team-filter ...] [--label ...] [--limit 25] [--cursor ] linear-remote issues search [--limit 25] linear-remote issues create --title --team [--project ] [--body "..."|--body @file] [--labels a,b] [--priority 0-4] [--assignee ] linear-remote issues create --from-markdown [--team ] # killer feature linear-remote issues update [--title ...] [--state ...] [--assignee ...] [--labels a,b] [--priority N] [--project ...] linear-remote issues move [--wait] [--timeout 60] linear-remote issues assign linear-remote comments add # accepts @path for file input linear-remote comments list linear-remote projects list [--team-filter ] linear-remote projects overview [--bucket-limit 25] linear-remote teams list linear-remote states linear-remote labels [--team-filter ] linear-remote cycles linear-remote whoami [--json] # identity for `agent-plus refresh` ("what's my linear identity") ``` All list/show commands emit JSON to stdout. Use `--pretty` for indentation. Every payload carries a top-level `tool: {name, version}` field so you can self-diagnose version drift directly from the output. Run `linear-remote --version` to print the version without a command. ### jq recommendation Pipe through `jq` to slice out the bits you need instead of paging the full JSON into context. Examples: ```bash # Just the open-issue identifiers from a project overview linear-remote projects overview 'Agent Plus' | jq -r '.issuesByState.inProgress[].identifier' # Title + state for one issue, no comments tree linear-remote issues get LOA-229 | jq '{id: .identifier, title, state: .state.name}' # Drop the tool meta when piping an issue payload to another tool linear-remote issues get LOA-229 | jq 'del(.tool)' ``` ## Design rules (agent-plus patterns) 1. **Aggregate server-side.** `issues get --include-comments --include-relations` returns the whole context tree in one call. `projects overview` bundles project meta + milestones + state-bucketed issues + recent activity. 2. **Resolve by name.** Pass `--team LOA`, `--project 'Agent Plus'`, `--state 'In Progress'`, `--assignee alice@example.com`. The CLI resolves UUIDs internally, with `lru_cache` on enum lookups so `update + move` in one invocation doesn't re-query. 3. **Accept either ID format.** Every issue argument accepts the human key (`LOA-229`) or the UUID. Free-text falls through to search with ambiguity surfacing candidates. 4. **`--wait` on webhook-driven transitions.** `issues move --wait` polls `issue.state.name` every 3s until it matches the target, 60s default, override with `--timeout`. On timeout: non-zero exit with partial JSON. Instant mutations return immediately without polling. 5. **`--json` is the default.** No human-prose output paths. 6. **Zero API-key leakage.** Every API response walks through `_scrub()` before emission — masks `apiKey`, `token`, `secret`, `webhookSecret`, `password`, and similar. A canary-value test asserts a known secret substring never appears in any output. ## `--from-markdown` contract - YAML frontmatter (optional): `team`, `project`, `labels` (list or inline), `assignee`, `priority` (0-4), `title` (overrides H1). - First `# H1` → title. Everything after → description. - `` stripped (Linear renders them as visible text). - `--team` flag overrides frontmatter; frontmatter overrides `LINEAR_TEAM_ID`. ## Pagination List commands return `{nodes: [...], pageInfo: {hasNextPage, endCursor}}`. Pass `--cursor ` for the next page. `--limit` default 25, max 100. ## Config precedence (highest first) 1. `--api-key` / `--team` CLI flags 2. `--env-file ` 3. `.env.local` / `.env` walked up from cwd (closest wins) 4. Shell env Only `LINEAR_*` prefixed vars are picked up. ## Error message contract Every error path emits problem + cause + fix + link: - Missing key → "Set in project `.env` or `.env.local` (keys prefixed `LINEAR_`), or `~/.claude/settings.json`. Get one: https://linear.app/settings/api" - 401 → "API key rejected. Check for whitespace/truncation. Rotate at https://linear.app/settings/api" - 403 → "Key lacks access to this workspace or resource. Confirm you're a member and the key belongs to it." - GraphQL field-level errors → the `path` and `message` surfaced verbatim so you can see which field failed. - 429 → "Rate-limited by Linear. Retry after s (Retry-After header). Linear's complexity budget is ~1500/hr." ## When NOT to use this — fall back to the Linear GraphQL API directly **This wrapper's write surface is deliberately narrow** (issues CRUD + move/assign, comments add/list, projects list/overview, read-only teams/states/labels/cycles). For anything outside that surface, don't try to bend `linear-remote` flags to fit — drop straight to `curl https://api.linear.app/graphql -H "Authorization: $LINEAR_API_KEY"` with a hand-written GraphQL document. The API key is already in scope; the only thing the wrapper adds is name resolution and scrubbing, and neither helps you when the operation isn't wrapped at all. Specific cases where you should hit GraphQL directly, not `linear-remote`: - **Project milestone CRUD** (create / update / delete milestones, reorder, set target dates). `projects overview` reads milestones; there's no `milestones` subcommand for writes. Use `projectMilestoneCreate` / `projectMilestoneUpdate` / `projectMilestoneDelete` mutations. - **Workflow state CRUD** (add a new state to a team, rename, change color, reorder, archive). `states ` is read-only. Use `workflowStateCreate` / `workflowStateUpdate` / `workflowStateArchive`. - **Cycle management beyond listing** (create a cycle, shift dates, close/uncomplete). `cycles ` is read-only. Use `cycleCreate` / `cycleUpdate`. - **Team / workspace admin** (create teams, change team settings, invite members, manage roles, org-level config). Not wrapped at all. Use `teamCreate` / `teamUpdate` / `teamMembershipCreate` and the org mutations. - **Webhook management and integration config** (register/rotate webhooks, configure GitHub/Slack/Intercom integrations, OAuth app settings). Not wrapped. Use `webhookCreate` / `webhookUpdate` / `integrationRequest` and friends. - **Documents, initiatives-beyond-read, roadmaps, custom views, custom fields** — none are wrapped. Use `documentCreate` / `initiativeCreate` / `initiativeUpdate` / `roadmap*` / `customView*` mutations directly, and consult Linear's schema introspection (`query { __schema { mutationType { fields { name } } } }`) if you're unsure of the field name. **Don't get stuck in a loop.** If `linear-remote --help` doesn't show a subcommand for the write you need, or a command returns "unknown subcommand" / "unsupported operation", stop retrying with different flags — write the GraphQL query/mutation yourself and `curl` it. The wrapper exists to make *reading and common writes* faster; it's not trying to be a full GraphQL client, and padding it out with one-off mutations defeats the point. ## What it doesn't do Deliberately out of scope for v1: - Cycle / milestone CRUD (read-only). - Initiative CRUD. - Team / workspace management. - Custom field mutations. - Webhook configuration. - Cross-issue relation mutations (`relate`). Relations surface in `issues get` read-only. - OAuth. Personal API key only — avoids the browser-auth wall that the MCP hits. Use the Linear UI, the MCP, or raw GraphQL for those. This plugin is read-first Linear work plus the common write surface (issue create/update/move, comments add). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [osouthgate](https://github.com/osouthgate) - **Source:** [osouthgate/agent-plus-skills](https://github.com/osouthgate/agent-plus-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-osouthgate-agent-plus-skills-linear-remote - Seller: https://agentstack.voostack.com/s/osouthgate - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.