feat: add `api` subcommand for raw GraphQL access by bendrucker · Pull Request #121 · schpet/linear-cli

bendrucker · 2026-02-03T05:23:05Z

Adds a linear api subcommand for making raw GraphQL requests, mirroring gh api conventions.

Changes

Accepts a GraphQL query as a positional arg, from stdin with -, or via auto-detected piped input
--variable key=value for typed variable coercion (booleans, numbers, null, @file for file reads, @- for stdin)
--variables-json '{"key": "value"}' for passing all variables as a JSON object (merged with --variable, which takes precedence)
--paginate walks pageInfo.endCursor automatically and outputs concatenated nodes array
--silent suppresses response output while exit code still reflects errors
Pretty-prints JSON when stdout is a TTY, raw JSON otherwise for piping to jq
Exits with code 1 on HTTP errors (status >= 400) and GraphQL-level errors
Uses raw fetch so users see the exact server response including both data and errors fields

Testing

Snapshot tests using MockLinearServer cover query resolution, variable handling (type coercion, @file, --variables-json, precedence), output modes, pagination (multi-page, single-page, non-connection), auth errors, and --silent behavior for both successful and HTTP error responses
Manual testing against live Linear API: cycles, workflow states, notifications (with --paginate), non-existent issue lookup, variable type mismatch errors, stdin piping

Use `after` instead of `endCursor` as the injected pagination variable to match Linear's GraphQL schema conventions. Add tests for: no API key, null/false coercion, values containing equals signs, single-page pagination, non-connection pagination with --paginate, and file-not-found errors for -F @path.

bendrucker · 2026-02-03T17:20:42Z

❤️ I also need to kick the tires on this a bit, feel free to review but I'm gonna convert back to a draft pending a bit more manual testing (and CI fix).

schpet

i think in general, at least to start, going with a more json oriented api might be more simple and easy? open to ideas but that's my hunch

src/commands/api.ts

Redesign the api subcommand variable interface for GraphQL-native semantics: - --variable key=value (repeated) with type coercion and @file support - --variables-json for complex nested objects - --variable takes precedence over --variables-json on key conflicts - Custom Cliffy Type for key=value parsing instead of hand-rolled split - Fix deno fmt issue on api-filter.json fixture

bendrucker · 2026-02-04T16:29:20Z

Ran claude --print (Sonnet) with the skill doc as system prompt to test whether agents can correctly use the redesigned variable flags. 5 prompts × 3 runs for 15 samples.

Results

Prompt	Runs	Flag usage	Score
Single string variable (`--variable id=abc-123`)	3/3 correct	`--variable`	3/3
Numeric variable (`--variable first=10`)	3/3 correct	`--variable`	3/3
Complex nested filter (IssueFilter)	3/3 correct	`--variables-json`	3/3
Mutation with multiple variables	3/3 correct	`--variable` × 2	3/3
Mixed types (string + numeric filter)	3/3 correct	`--variable` × 2	3/3

No confusion between the two flags across any run
Values with spaces handled correctly (--variable title='Fix login bug')
Type coercion worked as expected (numeric values passed as --variable first=10 without quoting)

Sample Outputs

Simple Variable

linear api 'query($id: String\!) { issue(id: $id) { id identifier title } }' --variable id=abc-123

Complex Filter

linear api 'query($filter: IssueFilter\!) { issues(filter: $filter) { nodes { identifier title } } }' \
  --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}'

Multiple Variables

linear api 'mutation($title: String\!, $teamId: String\!) { issueCreate(input: { title: $title, teamId: $teamId }) { success issue { id identifier title } } }' \
  --variable title='Fix login bug' --variable teamId=team-xyz

Methodology

Model: Claude Sonnet via claude --print --model sonnet
System prompt: full SKILL.md content
Each prompt explicitly asked for parameterized GraphQL with variables (to avoid the agent correctly choosing higher-level CLI commands like linear issue view)
3 independent runs per prompt to check consistency

The --silent flag was not suppressing output when the API returned HTTP 400+ status codes in both executeSingle and executePaginated paths.

bendrucker · 2026-02-06T19:11:04Z

Ready for review! Did another self-review/testing pass on this, and only came up with 9647a7d.

schpet

couple changes - let me know if you agree! open to push back. also depending on your bandwidth, i'm happy to make the changes i suggested for you.

schpet · 2026-02-07T18:03:10Z

src/commands/api.ts

+  variables: Record<string, unknown>,
+  headers: Record<string, string>,
+  silent: boolean,
+): Promise<void> {


i'm worried this pagination strategy only supports certain graphql queries. e.g. if a graphql document is supplied that has two different fields, it will not work right?

linear api 'query GetBoth($after: String) { viewer { assignedIssues(first: 2, after: $after) { nodes { identifier } pageInfo { hasNextPage endCursor } } createdIssues(first: 2, after: $after) { nodes { identifier } pageInfo { hasNextPage endCursor } } } }' --paginate

can you either change this to work reliably, or remove the pagination feature? my recommendation would be to omit it from this PR so we can land it, and if you determine reliable pagination is viable to implement that in a follow up PR.

if dropping it, perhaps we can bake in someting into the help text that helps agents understand they need to paginate stuff, i.e. suggest using pageInfo and cursor based pagination, something like that.

Good flag, I've used the paginate flag heavily with gh, but this is a legitimate sharp edge. I'll look into how gh attempts to deal with this, if at all (e.g., does it error when --paginate is used with an incompatible query?). If there's no clean and simple answer, taking it out sounds fine.

Looked into it — gh api --paginate has the exact same limitation, it just silently paginates the first connection and ignores the rest. Added detection that errors if there are multiple connections, with guidance to paginate manually. Also added test coverage for the nested connection case (sub-issues inside issues) to make sure that doesn't false-positive.

schpet · 2026-02-07T18:14:28Z

src/commands/api.ts

+  return variables
+}
+
+async function resolveTypedValue(value: string): Promise<unknown> {


this relates to prev discussion

without GraphQL schema type information, there's no way to know if "007" should be string "007" or number 7

repro/explanation here:
https://gist.github.com/schpetbot/60dc745b48cd1fe1f7cf31a9d60421e2

i DO think you could do this with graphql, but are you up for omitting this way of providing variables and doing json to start, and splitting the variable entry tuple parsing stuff on follow up PR?

Sure, similar to above I will think on this a little and if there's is no simple answer I'll cut this into a series of 2+ stacked PRs so you can land the simple parts and we can keep iterating on the trickier bits.

Added a roundtrip check that handles this plus a bunch of adjacent cases — hex, octal, leading +, trailing decimals like 1.0, etc. all stay as strings. Added test coverage for leading zeros and scientific notation specifically. --variables-json is still there as the escape hatch.

bendrucker · 2026-02-08T00:54:00Z

Added workarounds for both comments, but happy to back these features out for this PR as well.

String(Number(value)) === value prevents "007" from becoming 7 and "1e5" from becoming 100000.

gh api --paginate silently paginates only the first connection. Instead of replicating that footgun, detect multiple connections in the response and error with guidance to paginate manually.

feat: add api subcommand for raw GraphQL access

f84f510

bendrucker added 2 commits February 2, 2026 21:31

fix: join long line to pass deno fmt check

4dc1124

revert unrelated regenerated reference docs

4f99d66

bendrucker added 2 commits February 2, 2026 22:52

feat: add --paginate, --silent, @file variables, and GraphQL error ex…

02a9fad

…it codes

bendrucker marked this pull request as draft February 3, 2026 17:21

schpet reviewed Feb 3, 2026

View reviewed changes

src/commands/api.ts Show resolved Hide resolved

src/commands/api.ts Show resolved Hide resolved

fix: respect --silent flag for HTTP error responses

9647a7d

The --silent flag was not suppressing output when the API returned HTTP 400+ status codes in both executeSingle and executePaginated paths.

bendrucker marked this pull request as ready for review February 6, 2026 17:56

Merge branch 'main' into add-api-subcommand

351b945

schpet requested changes Feb 7, 2026

View reviewed changes

bendrucker added 2 commits February 7, 2026 17:03

fix: use roundtrip check for --variable number coercion

63921a3

String(Number(value)) === value prevents "007" from becoming 7 and "1e5" from becoming 100000.

feat: detect and error on multi-connection --paginate queries

b4b50eb

gh api --paginate silently paginates only the first connection. Instead of replicating that footgun, detect multiple connections in the response and error with guidance to paginate manually.

bendrucker force-pushed the add-api-subcommand branch from 26551da to b4b50eb Compare February 8, 2026 01:03

Conversation

bendrucker commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Related

Uh oh!

bendrucker commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schpet commented Feb 3, 2026

Uh oh!

bendrucker commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schpet left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bendrucker commented Feb 4, 2026

Results

Sample Outputs

Simple Variable

Complex Filter

Multiple Variables

Methodology

Uh oh!

bendrucker commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schpet left a comment

Choose a reason for hiding this comment

Uh oh!

schpet Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

bendrucker Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

bendrucker Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

schpet Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

bendrucker Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

bendrucker Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

bendrucker commented Feb 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bendrucker commented Feb 3, 2026 •

edited

Loading

bendrucker commented Feb 3, 2026 •

edited

Loading

bendrucker commented Feb 3, 2026 •

edited

Loading

bendrucker commented Feb 6, 2026 •

edited

Loading