Add --compact and --fields flags for token-efficient output

[EthycalOne]

Add --compact and --fields flags for token-efficient output

Problem

linearis is positioned for "LLM agents and humans who prefer structured data" (from package.json description), and the usage two-tier discovery pattern materially beats the official Linear MCP at session bootstrap. But the actual response payloads are still full-shape, pretty-printed JSON via:

// src/common/output.ts
export function outputSuccess(data: unknown): void {
  console.log(JSON.stringify(data, null, 2));
}

For agent consumers this leaves real token waste on the table:

• Pretty-printed JSON is ~40–50% whitespace.
• The CompleteIssueFields fragment returns ~30 fields per issue (state, assignee, team, project, labels, cycle, milestone, parent, children, relations, inverseRelations, …). A 50-issue issues list is ~25–40k tokens at default; an agent that only needs identifier + title + state.name can't trim it.

Today the only workaround is post-processing with jq in the agent's bash call, which is framing the problem on the agent side rather than at the CLI boundary where the same data shape is needed by every consumer.

Proposal

Add two global output-shaping flags (mirrors --api-token's plumbing):

• --compact — emit single-line JSON (no indent). Pure whitespace removal, no shape change.
• --fields <list> — comma-separated dot-paths to include, preserving nested object shape. Supports mid-path array traversal so --fields labels.nodes.name returns {"labels":{"nodes":[{"name":"bug"}, …]}}.

Examples

$ linearis issues list --limit 1
[
  {
    "identifier": "ENG-1",
    "title": "Fix login bug",
    "state": { "id": "...", "name": "In Progress", "type": "started" },
    "assignee": { ... },
    "team": { ... },
    "project": { ... },
    "labels": { "nodes": [...] },
    ...
  }
]

$ linearis --compact --fields identifier,title,state.name issues list --limit 1
[{"identifier":"ENG-1","title":"Fix login bug","state":{"name":"In Progress"}}]

A 50-issue list goes from ~25–40k tokens to ~2–3k tokens with both flags applied.

Default behavior unchanged

With neither flag set, output is the same indented full-shape JSON as today. Error envelopes (outputError, outputAuthError) are intentionally left pretty-printed — they're read by humans and the structure should remain stable.

Implementation sketch

I have a working branch ready (~218 LOC, 4 files touched, all existing tests pass + 10 new cases for the helpers). Happy to PR if greenlit. Approach:

• Single change site: outputSuccess in src/common/output.ts. Module-level currentOutputOptions populated once via program.hook("preAction", (_t, action) => setOutputOptions(getRootOpts(action))) in main.ts. Keeps all ~120 existing outputSuccess(result) call sites across 13 command modules untouched.
• Field selection is a small recursive pickFields(value, paths[]) helper in output.ts. No codegen interaction — the data has already been serialized to a POJO by the time it reaches outputSuccess. Mirrors the dot-path-with-array-traversal pattern Finesssee/linear-cli uses in Rust (select_fields/set_path).
• CommandOptions gets two optional fields (compact?: boolean, fields?: string[]).
• parseFieldsList(value) is exported as a commander option-parser so the CLI gets a string[] (with trim + empty-entry filtering) rather than each command re-parsing.

Out of scope for v1

• Wildcards / array-index syntax in --fields (e.g. items[].title, state.*).
• Trimming outputError/outputAuthError — error structure is a separate concern.

Questions for maintainers before I PR

1. Plumbing route: I went with the preAction-hook + module-state route to avoid touching all 120 outputSuccess(result) call sites. The alternative is making outputSuccess(data, opts?) accept opts explicitly and threading getRootOpts(command) through every command. Cleaner functionally but invasive. Preference?
2. Scope: PR both flags together as one feat(output): commit, or split into two PRs (--compact first as a trivially-safe change, --fields second)?
3. Error-path behavior: keep outputError/outputAuthError pretty-printed regardless of --compact, or also honor the flag for stderr? My draft keeps them unchanged.

Happy to push the draft branch to a fork if it'd help review, but waiting on direction here first per CONTRIBUTING.md ("Please open an issue first to discuss" for larger features).

[linear]

LIN-151

[iamfj]

Thanks @EthycalOne for writing this up. I like the idea, and I agree this is a real problem for Linearis' agent use case.

The direction makes sense to me: --compact is low risk, and --fields fits well as a post-API output shaping step. I do not see this as an API latency or rate-limit optimization, and I do not think it needs to be. The value is reducing token usage at the CLI boundary for agent consumers.

I also like that this keeps the default behavior unchanged and stays with JSON. I have already played around with JSONL and TOON when they were getting hype, but my benchmarks did not show a meaningful improvement for our use case. Output shaping on top of regular JSON feels like the better fit.

Before moving to implementation, I want to prepare a proper design for this so we get the CLI contract and edge cases right. The concept you described is solid, though.

I will address this in the upcoming weeks and let you know when there is something ready to test.

[EthycalOne]

Thanks @iamfj — sounds great, happy to wait on your design pass. Sharing two measured findings from running my draft against a real workspace in case they're useful as input:

Measured savings (50 issues, cl100k_base tokens):

variant	bytes	tokens	saved
default	33,493	9,403	—
--compact	30,676	8,570	9%
--compact --fields nodes.identifier,nodes.title,nodes.state.name	920	220	98%

So the headline "~40k → ~2–3k" claim holds end-to-end, but the breakdown is different than I framed it in the issue: --compact alone is only a ~9% win on real Linear payloads (they're ~91% character density — lots of IDs and description text, less whitespace than I estimated). --fields is doing essentially all the work.

Design input — wrapper-shape gotcha worth deciding on:

Connection responses wrap in {nodes: [...], pageInfo}, so the natural-feeling path (--fields identifier,title) returns {} because none of those exist at top level. You have to descend through nodes. (--fields nodes.identifier,nodes.title,nodes.state.name). My draft handles this correctly, but it's a usability cliff for agents. Two design choices worth weighing:

1. Auto-descend into nodes when the top-level shape is a connection — --fields identifier,title Just Works on list endpoints
2. Wildcard / array-index syntax (nodes[].identifier, nodes.*.identifier) — explicit, no magic
3. Status quo (require nodes.) — simplest, but every agent will hit {} once

I deliberately punted on this in v1 by requiring nodes. prefix, but it's the kind of CLI-contract decision your design pass should probably lock in early.

Will hold the PR; let me know when there's something to test.