linear-sdk-cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Release Please generates this file from Conventional Commits. Feature and fix pu
 not edit it directly; their squash-commit titles are the release-note source of truth. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0](https://github.com/zhendalf/linear-sdk-cli/compare/v0.7.2...v0.8.0) (2026-09-29)
+
+### Features
+
+- **auth:** persist app identity credentials ([#84](https://github.com/zhendalf/linear-sdk-cli/issues/84)) ([7d7ec19](https://github.com/zhendalf/linear-sdk-cli/commit/7d7ec19cb94cf43fb524dc1dd807b4d7d1c67515))
+
+### Bug Fixes
+
+- improve CLI onboarding and JSON error consistency ([#59](https://github.com/zhendalf/linear-sdk-cli/issues/59)) ([4444c38](https://github.com/zhendalf/linear-sdk-cli/commit/4444c38f05bc4f442da1e44582eafb35b8e342d1))
+
+## [0.7.2](https://github.com/zhendalf/linear-sdk-cli/compare/v0.7.1...v0.7.2) (2026-09-28)
+
+### Bug Fixes
+
+- **deps:** complete SDK and formatter upgrades ([#82](https://github.com/zhendalf/linear-sdk-cli/issues/82)) ([9ba7d6f](https://github.com/zhendalf/linear-sdk-cli/commit/9ba7d6ff77a1d7e9d63bc1d4e4957aed5d6a1ed4))
+- **deps:** update compatible dependency versions ([6e3e462](https://github.com/zhendalf/linear-sdk-cli/commit/6e3e46245088eb923886f6c29c3f8ec7d463ffa6))
+
 ## [0.7.1](https://github.com/zhendalf/linear-sdk-cli/compare/v0.7.0...v0.7.1) (2026-09-20)
 
 ### Bug Fixes

package/COVERAGE.md

@@ -1,12 +1,12 @@
 # SDK Coverage Audit
 
-Generated by `bun run audit:coverage`. Total LinearClient members: **476**.
+Generated by `bun run audit:coverage`. Total LinearClient members: **480**.
 
 | Status   | Count | Meaning                                         |
 | -------- | ----- | ----------------------------------------------- |
 | curated  | 107   | Has a first-class CLI command                   |
-| raw-only | 144   | Reachable via `linear api` (no bespoke command) |
-| excluded | 225   | Out of scope (admin/integration/SDK plumbing)   |
+| raw-only | 145   | Reachable via `linear api` (no bespoke command) |
+| excluded | 228   | Out of scope (admin/integration/SDK plumbing)   |
 
 Every member is classified — CI fails otherwise. `raw-only` members are still
 100% reachable through the raw GraphQL escape hatch; they simply lack a tailored command.
@@ -125,7 +125,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `workflowState` — state
 - `workflowStates` — state
 
-## Excluded (225)
+## Excluded (228)
 
 - `agentActivities` — specialized/raw api only
 - `agentActivity` — specialized/raw api only
@@ -235,7 +235,10 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `integrationGithubImportRefresh` — integration/import (raw api only)
 - `integrationGithubRemoveCodeAccess` — integration/import (raw api only)
 - `integrationGitlabConnect` — integration/import (raw api only)
+- `integrationGitlabRotate` — integration/import (raw api only)
 - `integrationGitlabTestConnection` — integration/import (raw api only)
+- `integrationGitlabUpdateRotationSettings` — integration/import (raw api only)
+- `integrationGitlabUpdateToken` — integration/import (raw api only)
 - `integrationGong` — integration/import (raw api only)
 - `integrationGoogleSheets` — integration/import (raw api only)
 - `integrationHasScopes` — integration/import (raw api only)
@@ -353,7 +356,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `userUnlinkFromIdentityProvider` — admin/enterprise (raw api only)
 - `userViewPreferences` — specialized/raw api only
 
-## Raw-only (144)
+## Raw-only (145)
 
 <details><summary>Show</summary>
 
@@ -405,6 +408,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `deleteTeamCycles`
 - `deleteTeamKey`
 - `deleteTeamMembership`
+- `dependencyPackageMetadata`
 - `documentContentHistory`
 - `emailIntakeAddress`
 - `emailIntakeAddressRefreshSesDomainStatus`

package/README.md

@@ -121,9 +121,10 @@ branch, so most issue commands let you omit the id entirely.
 For a person at a terminal, `linear auth login` uses browser Authorization Code + PKCE and the
 default `actor=user`. Existing personal API keys and invocation-scoped OAuth access tokens remain
 supported. Explicit `--api-key` or `--access-token` flags override environment credentials;
-without a credential flag the CLI reads `LINEAR_API_KEY` or `LINEAR_ACCESS_TOKEN`. If both kinds
-are supplied at the same precedence level, the CLI fails rather than silently choosing a Linear
-actor.
+without a credential flag the CLI reads `LINEAR_API_KEY`, `LINEAR_ACCESS_TOKEN`, or the pair
+`LINEAR_CLIENT_ID` / `LINEAR_CLIENT_SECRET`. Mixing credential types in the environment fails
+rather than silently choosing a Linear actor. Client credentials must be supplied together;
+explicit credential flags still override all environment credentials.
 
 > **Credential trust boundary.** A secret is **never** read from a project-local
 > `.linear.toml` — only non-secret settings live there — so a key can't be committed by accident.
@@ -159,7 +160,7 @@ store lock. `--admin` explicitly adds the admin scope; it is never implicit.
 `--no-browser` is useful over SSH only when the machine running the CLI is also reachable as the
 browser's loopback host; Linear does not currently document a device-code flow. Override a
 separately registered public client's identity with `LINEAR_OAUTH_CLIENT_ID` and its exact callback
-with `LINEAR_OAUTH_REDIRECT_URI`. No OAuth client secret is embedded, accepted, or stored.
+with `LINEAR_OAUTH_REDIRECT_URI`. No OAuth client secret is embedded or used for browser login.
 
 For a personal API key, `auth login --key -` reads stdin, validates the viewer/workspace, stores the
 key in the system keyring by default, and writes only a marker to the config. `--plaintext` is an
@@ -209,8 +210,7 @@ await child.exited;
 
 Call `tokens.invalidate()` (or `getAccessToken({ forceRefresh: true })`) before one bounded retry
 when Linear rejects the token with `401`. Client-credentials tokens do not have refresh tokens;
-renewal is another authenticated exchange. A short-lived/serverless process should use a secure
-shared token cache or central broker rather than minting a new 30-day token on every invocation.
+renewal is another authenticated exchange. For CI and scheduled automation, request a fresh token at the start of each run, as Linear recommends.
 
 For an app installed into multiple workspaces, use Authorization Code with `actor=app` instead and
 store each installation's rotating refresh token encrypted in the host. That hosted app lifecycle
@@ -223,13 +223,64 @@ webhooks. App actors cannot request the `admin` scope. See Linear's
 [app-actor authorization](https://linear.app/developers/oauth-actor-authorization), and
 [agent guide](https://linear.app/developers/agents).
 
-Hosted app tokens supplied through `LINEAR_ACCESS_TOKEN` remain invocation-scoped. The only OAuth
-tokens persisted by the CLI are human browser-login sessions, stored as an isolated per-workspace
-keyring record; the CLI never persists or uses an OAuth client secret.
+For persistent app identity on a local machine, enable client credentials in your Linear OAuth
+app, then sign in once:
+
+```sh
+# Supply the secret through stdin from your secret manager.
+linear auth login --app --client-id YOUR_CLIENT_ID --client-secret -
+linear auth status --json
+linear issue list --json
+```
+
+`--client-credentials` is an alias for `--app`. `--client-secret -` reads stdin until EOF;
+otherwise the client ID and secret default to `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET`.
+The client ID also accepts the existing `LINEAR_OAUTH_CLIENT_ID` fallback during explicit login.
+Login validates the token and workspace before storing credentials.
+
+By default, app credentials go into an isolated `app:<workspace>` OS keyring account; config files
+contain only a marker. On headless hosts, explicitly select private-file storage:
+
+```sh
+linear auth login --client-credentials --plaintext --client-id YOUR_CLIENT_ID --client-secret -
+# In a new shell, under the same user and config directory:
+linear auth status --json
+linear issue list --json
+```
+
+`--plaintext` stores client credentials in `$XDG_CONFIG_HOME/linear/config.toml` (or
+`~/.config/linear/config.toml`) with `0600` permissions, and makes its `linear` directory private
+with `0700` permissions. There is no automatic plaintext fallback for app credentials. The directory
+must be on persistent storage to survive container replacement, and agent subprocesses must have
+access to the same user config. Switching storage removes the previous copy of the app credentials;
+replacing an existing keyring profile requires access to that keyring.
+
+Use `--read-only` to request only `read`, or `--scope read,comments:create` for custom app scopes
+(default: `read,write`). App actors cannot request `--admin` or an `admin` scope. Linear must have
+client credentials enabled for the app. Changing scopes can revoke existing app tokens, so use
+the same scopes across hosts.
+
+For environment-only authentication, supply `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` from
+your platform's secret manager, then invoke `linear` directly. Optional `LINEAR_CLIENT_SCOPES`
+configures the comma-separated scopes. This mode overrides stored profiles and never writes
+credentials or tokens to config or cache files. Only an explicit `auth login --client-credentials`
+persists these environment credentials.
+
+Each invocation obtains a fresh token on its first API request, caches it in memory, renews before
+expiry, and retries an API request once with a new token after an authentication failure. This
+covers both SDK calls and raw GraphQL queries. Concurrent processes obtain their own tokens and do
+not share a disk token cache; within one process concurrent token exchanges are coalesced. No access
+or refresh token is persisted for app identity. `auth status` reports credential availability
+without making a network request, uses credential type `oauth-app` with source `user`, `keychain`,
+or `env`, and leaves `expiresAt` null because it has no stored token. It does not prove that Linear
+still accepts the client secret. Environment scopes describe configured requests, not independently
+verified grants. `auth token` continues to export personal API keys only. `auth logout` removes
+local app credentials and restores an existing personal API-key profile if present; it does not
+disable the app in Linear. Environment-only credentials must be unset separately.
 
 ### Multiple workspaces
 
-Credentials are stored per **workspace slug**. Browser and API-key login both derive the slug from
+Credentials are stored per **workspace slug**. Browser, app, and API-key login derive the slug from
 the authenticated organization; `--workspace` validates that the result matches:
 
 ```sh
@@ -243,7 +294,7 @@ linear --workspace other-org issue list    # use a specific workspace for one co
 linear auth logout --workspace acme        # revoke OAuth, then remove one credential
 ```
 
-Successful browser and API-key login also save `workspace = "<authenticated slug>"` in the discovered project config, preserving other settings and comments. If no config exists, login creates `.linear.toml` at the Git root (or cwd outside Git). Use `auth login --no-project` for credential-only login. Human output reports the association path; JSON includes `projectConfigPath` (null with `--no-project`). Credentials remain in the global credential store. Environment overrides still take precedence over this association.
+Successful browser, app, and API-key login also save `workspace = "<authenticated slug>"` in the discovered project config, preserving other settings and comments. If no config exists, login creates `.linear.toml` at the Git root (or cwd outside Git). Use `auth login --no-project` for credential-only login. Human output reports the association path; JSON includes `projectConfigPath` (null with `--no-project`). Credentials remain in the global credential store. Environment overrides still take precedence over this association.
 
 Global defaults are optional: login, credential adoption, and logout never choose a new one. Use `linear auth default <slug>` to explicitly select a global fallback. Removing that workspace clears its default without promoting another workspace. Existing defaults, including defaults imported from the reference CLI, are preserved on upgrade because older files cannot distinguish a user choice from an automatically assigned default. To opt out of a legacy default, remove the top-level `default_workspace` from the user config and, if present, `default` from the reference CLI's `credentials.toml`; retain the workspace entries.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",
@@ -71,18 +71,18 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
-    "@linear/sdk": "^95.1.0",
+    "@linear/sdk": "^97.0.0",
     "commander": "^15.0.0",
     "graphql": "^17.0.2",
     "picocolors": "^1.1.1",
-    "smol-toml": "^1.8.0"
+    "smol-toml": "^1.9.0"
   },
   "packageManager": "bun@1.4.2",
   "devDependencies": {
     "@types/bun": "^1.4.2",
-    "@types/node": "^26.6.2",
-    "oxfmt": "^0.68.0",
-    "oxlint": "^1.83.0",
+    "@types/node": "^26.6.3",
+    "oxfmt": "^0.71.0",
+    "oxlint": "^1.86.0",
     "typescript": "^7.0.2"
   }
 }

package/skills/linear-sdk-cli/SKILL.md

@@ -66,17 +66,43 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
    the 30-day app token in memory, renews before expiry, coalesces concurrent exchanges, and
    supports invalidation or forced renewal for one bounded retry after a `401`. Keep the client
    secret in the host's secret manager and inject only `LINEAR_ACCESS_TOKEN` into CLI children.
-   Serverless hosts need a secure shared token cache or broker so cold starts do not mint a new
-   token for every command.
+   For CI and scheduled automation, request a fresh token at the start of each run.
 
-3. **`--api-key <key>`** flag (per invocation) or **`LINEAR_API_KEY`** env var — best
+3. **Persistent app identity** with client credentials (enable this grant in the Linear app):
+
+   ```bash
+   linear auth login --app --client-id YOUR_CLIENT_ID --client-secret -
+   linear auth status --json
+   ```
+
+   `--client-credentials` is an alias for `--app`. Read the secret from stdin until EOF, or
+   explicitly log in using `LINEAR_CLIENT_ID` / `LINEAR_CLIENT_SECRET`. The default store is
+   the OS keyring; on headless hosts use explicit `--plaintext` to store client credentials in
+   the user config (`0600`, containing directory `0700`). Keep that directory on persistent
+   storage in containers and make it accessible to agent subprocesses under the same user.
+   There is no automatic plaintext fallback.
+
+   Commands obtain a fresh token per invocation and renew before expiry or once on authentication
+   failure, including raw GraphQL requests. Tokens remain in memory. Use `--read-only` for read
+   access or `--scope read,comments:create` for custom scopes (default `read,write`); app actors
+   cannot request `admin`. Keep scopes consistent across hosts to avoid revoking existing tokens.
+   Status reports `oauth-app`, the source, and configured scopes without validating credentials
+   remotely; expiry is null because there is no persisted token. Logout removes local app
+   credentials without disabling the app. `auth token` still exports personal API keys only.
+
+   Environment-only app auth also works directly: supply `LINEAR_CLIENT_ID` and
+   `LINEAR_CLIENT_SECRET` together, optionally `LINEAR_CLIENT_SCOPES`, then run `linear`.
+   It writes no config or cache files. Mixing these with environment API keys/access tokens
+   is rejected; explicit `--api-key` or `--access-token` flags override environment credentials.
+
+4. **`--api-key <key>`** flag (per invocation) or **`LINEAR_API_KEY`** env var — best
    for CI and ephemeral agent runs:
 
    ```bash
    LINEAR_API_KEY=lin_api_... linear whoami --json
    ```
 
-4. **Stored personal API-key credentials** via the explicit compatibility path:
+5. **Stored personal API-key credentials** via the explicit compatibility path:
 
    ```bash
    printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -
@@ -85,7 +111,7 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
    Passing `--key <value>` also works but exposes it in argv and produces a warning. API keys may
    use `--plaintext`; browser OAuth is always keyring-only.
 
-5. **Multiple workspaces** — store several OAuth or API-key credentials and select one per call with
+6. **Multiple workspaces** — store several OAuth or API-key credentials and select one per call with
    `--workspace <slug>`; set a default with `linear auth default <slug>`:
 
    ```bash
@@ -127,11 +153,12 @@ stderr), so it is always safe to pipe into `jq`. The envelope is a stable contra
   `--debug` the extra detail rides _inside_ that object as `error.detail`, so `--json --debug`
   stays parseable.
 
-Relations are **objects with ids**, on list rows and on `view` alike — `state: {id,name,type}`,
-`team: {id,key,name}`, `assignee: {id,displayName,email}`, `project`/`milestone: {id,name}`,
-`cycle: {id,number,name}`, `parent: {id,identifier}`, `labels: [{id,name}]` — so `.state.name`
-reads the same everywhere and the id you need to act on is already in hand. Issues also carry
-`archivedAt` and `trashed`; a deleted issue still views, and says so.
+Issue list rows use compact relations: `state: {name,type}`, `assignee: {displayName}`,
+`project: {name}`, and `labels: string[]`. They do not include `team` or `parent`.
+`issue view` returns richer relations with IDs, including `team`, `parent`, and label
+objects. Use `issue view <identifier> --json` when you need those relation IDs;
+inspect `linear commands issue list --json` or `linear commands issue view --json`
+for the exact shape. Both include `archivedAt` and `trashed`.
 
 ```bash
 linear issue list --json | jq -r '.[].identifier'
@@ -612,7 +639,7 @@ GRAPHQL
 linear api --query-file q.graphql --vars-file vars.json --paginate
 
 # Pipe data straight to jq (status notes go to stderr)
-linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'
+linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.issues.nodes[].title'
 ```
 
 `api` flags: `--query-file <path>` (`-` = stdin), `--var <k=v>` (repeatable string

package/skills/linear-sdk-cli/references/auth.md

@@ -75,17 +75,21 @@ Authenticate and select the workspace for this project
 linear auth login [options]
 ```
 
-| Option                 | Description                                                           |
-| ---------------------- | --------------------------------------------------------------------- |
-| `--no-project`         | save credentials without changing the project workspace               |
-| `--key <key>`          | use a personal API key ('-' reads it from stdin)                      |
-| `--plaintext`          | Store the key in the config file (0600) instead of the system keyring |
-| `--no-browser`         | print the authorization URL instead of opening it                     |
-| `--read-only`          | request read-only OAuth access                                        |
-| `--admin`              | explicitly add the OAuth admin scope                                  |
-| `--timeout <seconds>`  | seconds to wait for the loopback callback                             |
-| `--client-id <id>`     | OAuth client ID (defaults to the packaged CLI app)                    |
-| `--redirect-uri <uri>` | registered HTTP loopback callback URI                                 |
+| Option                     | Description                                                             |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `--no-project`             | save credentials without changing the project workspace                 |
+| `--key <key>`              | use a personal API key ('-' reads it from stdin)                        |
+| `--plaintext`              | Store API-key or app credentials in the private user config file (0600) |
+| `--no-browser`             | print the authorization URL instead of opening it                       |
+| `--read-only`              | request read-only OAuth access                                          |
+| `--admin`                  | explicitly add the OAuth admin scope                                    |
+| `--timeout <seconds>`      | seconds to wait for the loopback callback                               |
+| `--app`                    | sign in as an app using client credentials                              |
+| `--client-credentials`     | alias for --app                                                         |
+| `--scope <scopes>`         | comma-separated app scopes (default: read,write)                        |
+| `--client-secret <secret>` | app client secret ('-' reads stdin; defaults to LINEAR_CLIENT_SECRET)   |
+| `--client-id <id>`         | OAuth client ID (app: LINEAR_CLIENT_ID; browser: packaged CLI app)      |
+| `--redirect-uri <uri>`     | registered HTTP loopback callback URI                                   |
 
 **Output (`--json`)**: a receipt object
 

package/src/bin/linear.ts

@@ -6,7 +6,7 @@
  */
 
 import { CommanderError } from "commander";
-import { createProgram, parsedGlobalOptions, usageHint, suppressedHelp } from "../cli.js";
+import { createProgram, errorGlobalOptions, usageHint, suppressedHelp } from "../cli.js";
 import { Output } from "../output/format.js";
 import { CliError, ExitCode, normalizeError } from "../lib/errors.js";
 import { commandPath } from "../lib/options.js";
@@ -31,6 +31,8 @@ program.parseAsync(process.argv).catch((err) => {
     if (err.exitCode === 0) process.exit(0);
   }
 
+  const globals = errorGlobalOptions(program, process.argv.slice(2));
+
   // A group invoked bare (`linear notification`) is commander asking to show
   // that group's help and exit non-zero. It wrote the help to the stderr we
   // route through here, so print exactly that for a human — an envelope
@@ -38,7 +40,7 @@ program.parseAsync(process.argv).catch((err) => {
   // usage error under --json.
   if (err instanceof CommanderError && err.code === "commander.help") {
     const help = suppressedHelp(program);
-    if (help && parsedGlobalOptions(program).json !== true) {
+    if (help && globals.json !== true) {
       process.stderr.write(help.text);
       process.exit(ExitCode.Usage);
     }
@@ -46,11 +48,8 @@ program.parseAsync(process.argv).catch((err) => {
 
   const cliError = err instanceof CommanderError ? fromCommander(err) : normalizeError(err);
 
-  // Format the error the way the user asked for the output — from the globals
-  // commander parsed, so every spelling it accepts (`-j`, `-jq`, `--json`)
-  // reaches the envelope. Errors go to stderr, so that stream's TTY-ness decides
-  // colour, not stdout's.
-  const globals = parsedGlobalOptions(program);
+  // Recovered flags include trailing options after a value-validation failure.
+  // Errors go to stderr, so that stream determines color.
   const json = globals.json === true;
   const out = new Output({
     json,

package/src/cli.ts

@@ -3,7 +3,7 @@
  * Kept free of side effects so it can be imported by tests and the bin entry.
  */
 
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { addGlobalOptions, globalOptionKeys, unknownCommand, commandPath } from "./lib/options.js";
 import { registerMeta } from "./commands/meta.js";
 import { registerApi } from "./commands/api.js";
@@ -57,6 +57,21 @@ export function createProgram(): Command {
     // 0 arguments but got 2: issues, list." — true, and no help at all.
     .allowExcessArguments();
 
+  program.addHelpText(
+    "after",
+    [
+      "",
+      "Start here:",
+      "  linear auth status                    # check your connection",
+      "  linear auth login                     # connect if needed",
+      "  linear team list                      # find your team key",
+      "  linear issue list --assignee me        # find your work",
+      "  linear issue view TES-42               # read an issue",
+      "  linear issue list --help               # discover filters and examples",
+      "  linear commands issue list --json     # inspect options and JSON fields",
+    ].join("\n"),
+  );
+
   addGlobalOptions(program);
 
   // Phase 0: meta + escape hatch + completion.
@@ -140,17 +155,9 @@ export function createProgram(): Command {
  * The global options as commander actually parsed them, read back off the
  * command tree after `parseAsync` has thrown.
  *
- * The error boundary has no Context to ask — the failure may have happened
- * before any action ran — so it used to re-parse `process.argv` by hand with
- * `argv.includes("--json")`. That check did not know the `-j` alias, bundled
- * short flags (`-jq`) or any other spelling commander accepts, so `linear issue
- * view NOPE-1 -j` printed a plaintext error while `--json` printed the
- * envelope: an unparseable error stream for exactly the callers the envelope
- * exists for. Commander has already parsed whatever it got to before failing
- * (a bad option is reported only after the whole argument list is scanned), so
- * the boundary reads that instead of parsing again. Every global is registered
- * on every command and stored under the same key, so the flag is found
- * wherever on the command path it was given.
+ * The error boundary has no Context to ask because an option parser may fail
+ * before an action runs. Read explicitly supplied globals across the tree;
+ * errorGlobalOptions supplements these when trailing flags were not reached.
  */
 export function parsedGlobalOptions(program: Command): GlobalOptions {
   const keys = globalOptionKeys();
@@ -165,6 +172,75 @@ export function parsedGlobalOptions(program: Command): GlobalOptions {
   return merged as GlobalOptions;
 }
 
+/** Recover output flags after a value parser stops before reaching trailing flags.
+ * Parse a side-effect-free copy of the grammar: no actions, hooks, validation,
+ * credentials, or API calls. Commander still handles option values, clusters,
+ * aliases and `--`, so literal body text cannot turn on JSON mode.
+ */
+export function errorGlobalOptions(program: Command, args: string[]): GlobalOptions {
+  class RecoveryOption extends Option {
+    private readonly key: string;
+
+    constructor(source: Option) {
+      super(source.flags, source.description);
+      this.negate = source.negate;
+      this.key = source.attributeName();
+    }
+
+    override attributeName(): string {
+      return this.key;
+    }
+  }
+
+  const copy = (source: Command): Command => {
+    const cmd = new Command(source.name())
+      .aliases(source.aliases())
+      .allowExcessArguments()
+      .allowUnknownOption()
+      .helpOption(false)
+      .exitOverride()
+      .configureOutput({ writeOut: () => {}, writeErr: () => {} })
+      .action(() => {});
+    for (const option of source.options) {
+      // Preserve custom storage keys and negation semantics (notably the
+      // NoFlagOption globals behind --no-ansi / --no-color / --no-input).
+      cmd.addOption(new RecoveryOption(option));
+    }
+    for (const child of source.commands) cmd.addCommand(copy(child));
+    return cmd;
+  };
+  const grammar = copy(program).enablePositionalOptions();
+  try {
+    grammar.parse(args, { from: "user" });
+  } catch {
+    // A malformed or missing option value may still stop parsing; retain
+    // whatever was read and recover the boundary-only booleans below.
+  }
+
+  // An output flag can itself be consumed as the malformed value of the option
+  // before it (`--limit --json`). Recover only the booleans used by the error
+  // boundary, stopping at `--` and ignoring `--flag=<literal>` values. A short
+  // cluster counts only when every character is one of our boolean aliases.
+  const boundary: GlobalOptions = {};
+  for (const arg of args) {
+    if (arg === "--") break;
+    if (arg === "--json") boundary.json = true;
+    else if (arg === "--quiet") boundary.quiet = true;
+    else if (arg === "--debug") boundary.debug = true;
+    else if (arg === "--no-ansi" || arg === "--no-color") boundary.noAnsi = true;
+    else if (/^-[jq]+$/.test(arg)) {
+      if (arg.includes("j")) boundary.json = true;
+      if (arg.includes("q")) boundary.quiet = true;
+    }
+  }
+
+  return {
+    ...parsedGlobalOptions(grammar),
+    ...parsedGlobalOptions(program),
+    ...boundary,
+  };
+}
+
 function applyGlobalOptionsToAll(cmd: Command): void {
   for (const sub of cmd.commands) {
     // addGlobalOptions skips any global the command already declares itself, so

package/src/client.ts

@@ -4,10 +4,15 @@
 
 import { LinearClient } from "@linear/sdk";
 import { rotateOAuthCredential, type ResolvedConfig } from "./config.js";
-import { OAuthUserTokenProvider } from "./oauth.js";
+import {
+  ClientCredentialsTokenProvider,
+  OAuthUserTokenProvider,
+  type GetAccessTokenOptions,
+} from "./oauth.js";
 import { authError, normalizeError, CliError } from "./lib/errors.js";
 
 export function createClient(config: ResolvedConfig): LinearClient {
+  if (config.appCredential) return createRefreshingAppClient(config);
   if (config.oauthCredential) {
     return createRefreshingOAuthClient(config);
   }
@@ -27,21 +32,56 @@ export function createClient(config: ResolvedConfig): LinearClient {
   return new LinearClient({ apiKey: config.apiKey });
 }
 
+/** App credentials obtain a new token each invocation and renew before expiry or once on 401. */
+function createRefreshingAppClient(config: ResolvedConfig): LinearClient {
+  const provider = new ClientCredentialsTokenProvider(config.appCredential!);
+  return installTokenRenewal(
+    new LinearClient({ accessToken: "pending-app-token" }),
+    async (options) => (await provider.getAccessToken(options)).accessToken,
+  );
+}
+
+/** Both generated SDK requests and raw queries must cross the same token boundary. */
+function installTokenRenewal(
+  client: LinearClient,
+  getAccessToken: (options?: GetAccessTokenOptions) => Promise<string>,
+): LinearClient {
+  const run = async <T>(request: () => Promise<T>): Promise<T> => {
+    client.client.setHeader("Authorization", `Bearer ${await getAccessToken()}`);
+    try {
+      return await request();
+    } catch (err) {
+      if (!isAuthenticationFailure(err)) throw err;
+      client.client.setHeader(
+        "Authorization",
+        `Bearer ${await getAccessToken({ forceRefresh: true })}`,
+      );
+      return request();
+    }
+  };
+  const request = client.client.request.bind(client.client);
+  const rawRequest = client.client.rawRequest.bind(client.client);
+  client.client.request = (...args) => run(() => request(...args));
+  client.client.rawRequest = (...args) => run(() => rawRequest(...args));
+  return client;
+}
+
 function isAuthenticationFailure(err: unknown): boolean {
   const value = err as Record<string, any> | undefined;
   const status = value?.status ?? value?.response?.status ?? value?.raw?.response?.status;
   if (status === 401) return true;
+  if (/^authentication(?:error)?$/i.test(String(value?.type ?? ""))) return true;
   const errors = value?.response?.errors ?? value?.errors ?? value?.raw?.response?.errors;
   return (
     Array.isArray(errors) &&
     errors.some((item) => {
-      const type = `${item?.extensions?.type ?? ""} ${item?.extensions?.code ?? ""}`;
+      const type = `${item?.type ?? item?.extensions?.type ?? ""} ${item?.extensions?.code ?? ""}`;
       const message = `${item?.message ?? ""}`;
       return (
         /^(?:authentication(?:error)?|unauthorized|invalidtoken|invalid_token)$/i.test(
           type.trim(),
         ) ||
-        /authentication (?:failed|required)|unauthori[sz]ed|invalid (?:access )?token|token (?:expired|invalid)/i.test(
+        /unauthenticated|authentication (?:failed|required)|unauthori[sz]ed|invalid (?:access )?token|token (?:expired|invalid)/i.test(
           message,
         )
       );
@@ -56,21 +96,9 @@ function createRefreshingOAuthClient(config: ResolvedConfig): LinearClient {
     credential,
     persist: (previous, next) => rotateOAuthCredential(credential.workspace.urlKey, previous, next),
   });
-  const client = new LinearClient({ accessToken: credential.accessToken });
-  const original = client.client.request.bind(client.client);
-  client.client.request = async (document, variables, requestHeaders) => {
-    const accessToken = await provider.getAccessToken();
-    client.client.setHeader("Authorization", `Bearer ${accessToken}`);
-    try {
-      return await original(document, variables, requestHeaders);
-    } catch (err) {
-      if (!isAuthenticationFailure(err)) throw err;
-      const replacement = await provider.getAccessToken({ forceRefresh: true });
-      client.client.setHeader("Authorization", `Bearer ${replacement}`);
-      return original(document, variables, requestHeaders);
-    }
-  };
-  return client;
+  return installTokenRenewal(new LinearClient({ accessToken: credential.accessToken }), (options) =>
+    provider.getAccessToken(options),
+  );
 }
 
 /**

package/src/commands/issue.ts

@@ -290,7 +290,13 @@ export function registerIssue(program: Command): void {
           ctx.limit,
           ctx.defaultTeam,
         );
-        ctx.output.list(rows, listColumns(ctx), rows);
+        ctx.output.list(rows, listColumns(ctx), {
+          jsonRows: rows,
+          empty:
+            !opts.allStates && !opts.state?.length
+              ? "No unstarted issues assigned to you match these filters. Use --all-states to include in-progress and other states."
+              : undefined,
+        });
       }),
     );
   addFilterOptions(mine, { assignee: false }).addOption(