linear-sdk-cli 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -1,8 +1,21 @@
 # Changelog
 
-All notable changes to this project are documented here. The format is based on
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
-[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Release Please generates this file from Conventional Commits. Feature and fix pull requests do
+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.3.1](https://github.com/zhendalf/linear-sdk-cli/compare/v0.3.0...v0.3.1) (2026-08-28)
+
+### Bug Fixes
+
+- **release:** prevent changelog drift ([e8019a0](https://github.com/zhendalf/linear-sdk-cli/commit/e8019a0cc59182579237f9ec83138259fcd0615b))
+
+## [0.3.0](https://github.com/zhendalf/linear-sdk-cli/compare/v0.2.4...v0.3.0) (2026-08-28)
+
+### Features
+
+- **auth:** add browser OAuth login with PKCE (LIN-740) ([d5826e1](https://github.com/zhendalf/linear-sdk-cli/commit/d5826e1ebdc9015e876faa29b004f4953a190b43))
+- **auth:** support OAuth access tokens ([#28](https://github.com/zhendalf/linear-sdk-cli/issues/28)) ([4fecb6c](https://github.com/zhendalf/linear-sdk-cli/commit/4fecb6c1a40533804ff2fde5ace689d39c70d4bc))
 
 ## [0.2.4](https://github.com/zhendalf/linear-sdk-cli/compare/v0.2.3...v0.2.4) (2026-08-24)
 
@@ -33,27 +46,39 @@ All notable changes to this project are documented here. The format is based on
 ### Features
 
 - expand CLI workflows and terminal UX ([0fe31cc](https://github.com/zhendalf/linear-sdk-cli/commit/0fe31cca7e71d0fa6eee2b7c1461ecaf0a01103f))
+- **comments:** add explicit, notification-capable mentions with repeatable `--mention`
+  ([TES-738](https://linear.app/issue/TES-738)). Literal `@name` text remains Markdown; comment
+  commands resolve users exactly and prepend real Linear mention tokens.
 
 ### Bug Fixes
 
 - **ci:** give release dispatch repository context ([#15](https://github.com/zhendalf/linear-sdk-cli/issues/15)) ([e3f51e6](https://github.com/zhendalf/linear-sdk-cli/commit/e3f51e600102416f3bd3212578b364a13a452e49))
 
+### Changed
+
+- Replace ESLint with Oxlint while preserving the existing JavaScript and TypeScript checks.
+- Use TypeScript 7 for type-checking without source or configuration compatibility changes.
+
 ## [0.1.3](https://github.com/zhendalf/linear-sdk-cli/compare/v0.1.2...v0.1.3) (2026-08-24)
 
 ### Bug Fixes
 
 - **ci:** grant OIDC to automated publisher ([#7](https://github.com/zhendalf/linear-sdk-cli/issues/7)) ([acc6e4b](https://github.com/zhendalf/linear-sdk-cli/commit/acc6e4b9c4ab485ce39eeec7eb2c835892016e59))
 
-## [Unreleased]
+## [0.1.2](https://github.com/zhendalf/linear-sdk-cli/compare/v0.1.1...v0.1.2) (2026-08-24)
+
+### Dependencies
+
+- Upgrade the runtime and development dependencies ([#2](https://github.com/zhendalf/linear-sdk-cli/issues/2)).
+
+### Continuous Integration
+
+- Run verification on pull requests using the latest Bun release ([#3](https://github.com/zhendalf/linear-sdk-cli/issues/3)).
+
+## [0.1.1](https://github.com/zhendalf/linear-sdk-cli/releases/tag/v0.1.1) (2026-08-24)
 
 ### Added
 
-- **Explicit, notification-capable comment mentions (`--mention`, TES-738).** Ordinary `@name`
-  text remains literal Markdown. Comment-writing commands now accept repeatable
-  `--mention <name|email|me|id>`, resolve each user exactly, deduplicate repeats, and prepend real
-  Linear mention tokens as their own paragraph. The option is available on `issue comment`,
-  `comment add`, `comment reply`, and `comment update`, including the shared
-  `issue comment add/update` mounts.
 - **Every command declares its `--json` output, and `linear commands <path>` prints it (TES-610).**
   An agent driving the CLI cold guessed key names and filed false bugs (`.user` read as `.author`,
   `.parent` as `.parentId`); the field names were knowable only from the source. Each node of
@@ -326,11 +351,6 @@ true` is sent unless `--no-default-template` (also accepted under the reference'
 
 ### Changed
 
-- **Development linting now uses Oxlint instead of ESLint.** The migrated configuration preserves
-  the existing recommended JavaScript and TypeScript checks and underscore-prefixed unused-variable
-  exceptions while reducing the lint dependency tree and execution time.
-- **TypeScript 7 now powers type-checking.** The native compiler replaces TypeScript 6 without
-  source or configuration compatibility changes in this project.
 - **`--fields`, `--limit` and `--all` are refused on commands that never read them** (TES-637 (2),
   TES-596). All twelve globals are registered on every command so they can sit anywhere on the
   line, but `--fields` projects a _rendered_ result (a table or a detail block) and `--limit`/`--all`
@@ -835,7 +855,7 @@ column 36`), never an excerpt from a credential-bearing file, and strip control
 - **`roadmap delete` alias is now `rm`** (was `del`), matching the `rm` delete alias used by
   every other group.
 
-## [0.1.0]
+## [0.1.0] (2026-06-26)
 
 Initial release. An ergonomic CLI for Linear built on `@linear/sdk`, with human-readable output
 by default and a stable `--json` mode for scripts and agents.

package/MIGRATING.md

@@ -47,12 +47,13 @@ linear auth list        # …lists it, Storage: keychain
 ```
 
 If it does not — no keyring on this platform, or you used schpet's plaintext mode (`slug =
-"lin_api_…"` inline in `credentials.toml`, which we deliberately do not read) — `linear auth login`
-prompts (masked) and stores the key in the keyring; `--plaintext` keeps it in our `0600`
-`config.toml` instead. `auth migrate` moves plaintext credentials from that file into the keyring,
-same command name as theirs. Because the keyring entry is shared, `auth logout` here removes it for
-schpet too (and drops the slug from its list file, so neither tool reports a workspace whose key is
-gone). The API key is **never** read from a project `.linear.toml`.
+"lin_api_…"` inline in `credentials.toml`, which we deliberately do not read) — pipe the key to
+`linear auth login --key -`; `--plaintext` keeps it in our `0600` `config.toml` instead. Bare
+`linear auth login` now starts browser OAuth, so it never prompts for a personal API key. `auth
+migrate` moves plaintext credentials from our file into the keyring, same command name as theirs.
+Because the API-key entry is shared, `auth logout` here removes it for both tools (and drops the
+slug from schpet's list file, so neither reports a workspace whose key is gone). The API key is
+**never** read from a project `.linear.toml`.
 
 ## 3. Config — same files, same keys
 

package/README.md

@@ -103,51 +103,133 @@ branch, so most issue commands let you omit the id entirely.
 
 ## Authentication
 
-The CLI resolves your API key in this order: the `--api-key` flag → the `LINEAR_API_KEY`
-environment variable → a plaintext key in the user config file (`~/.config/linear/config.toml`,
-written `0600`) → the **OS keyring** (macOS Keychain, or `secret-tool` on Linux).
-
-> **Credential trust boundary.** The API key is **never** read from a project-local
+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.
+
+> **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.
 > A project may select one of your already-stored credentials with `workspace = "<slug>"`, but it
-> cannot provide or override the secret.
+> cannot provide or override the secret. Browser OAuth credentials are keyring-only; an access
+> token injected with `--access-token` or `LINEAR_ACCESS_TOKEN` remains invocation-scoped.
+
+```sh
+linear auth login                          # browser OAuth, read + write, actor=user
+linear auth login --read-only              # request only Linear's read scope
+linear auth login --no-browser             # print the URL; still waits on the loopback callback
+printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -  # personal API-key fallback
+linear auth status                         # credential kind and source (value redacted)
+linear auth logout --workspace acme        # revoke OAuth (if used) and remove the profile
+```
+
+Browser login generates a cryptographically random verifier and CSRF state, requires PKCE S256,
+opens Linear, and listens temporarily on the registered `127.0.0.1` callback. It validates the
+viewer and workspace before saving the access token, rotating refresh token, expiry, granted
+scopes, OAuth client identity, and workspace identity. The whole record lives only in the system
+keyring (`service = linear-cli`, `account = oauth:<workspace slug>`); the config file gets only
+non-secret `keyring = true` and `oauth = true` markers. Access tokens refresh before expiry and
+once after an authentication failure, with refresh-token rotation committed under the credential
+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.
+
+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
+API-key-only compatibility option. API-key entries use `account = <workspace slug>`, matching
+[schpet/linear-cli](https://github.com/schpet/linear-cli). Passing a key as `--key <value>` works but
+warns because argv is visible to other processes. `auth migrate` moves legacy plaintext keys into
+the keyring, and `auth token` exports stored API keys only; OAuth tokens are never printed.
+
+### Apps, agents, and service accounts
+
+Use an OAuth access token when the CLI runs inside an integration or agent:
 
 ```sh
-linear auth login                          # store a key (prompts, validates, saves to the keyring)
-linear auth login --plaintext              # …or keep it in the 0600 config file instead
-linear auth status                         # where the key came from (value redacted)
-linear auth migrate                        # move plaintext keys from the file into the keyring
-linear auth token                          # print the resolved key (for scripting)
+LINEAR_ACCESS_TOKEN="$access_token" linear whoami --json
+LINEAR_ACCESS_TOKEN="$access_token" linear issue list --json
 ```
 
-`auth login` stores the secret in the system keyring by default and writes only a
-`keyring = true` marker to the config file; where there is no keyring (other platforms, or a Linux
-box without `libsecret`) it falls back to the file, and says so. The keyring entry is
-`service = linear-cli`, `account = <workspace slug>` — the same convention as
-[schpet/linear-cli](https://github.com/schpet/linear-cli), so if you are coming from it your key is
-found without a re-login (`auth status` reports `Source: keychain`). Note the entry is shared:
-`auth logout` here removes it for both tools. `--key -` reads the key from stdin for scripts;
-passing it as `--key <value>` works but earns a warning, since argv is visible to other processes.
+The application host owns OAuth installation, refresh-token or client-credentials exchange,
+client-secret storage, and webhook processing; it injects only the current access token into each
+CLI invocation. The CLI passes it to `LinearClient({ accessToken })`, which sends the required
+Bearer authorization. Prefer the environment variable because a command-line token is visible to
+other processes and shell history.
+
+For a long-lived, single-workspace host, enable client credentials on the Linear OAuth app and keep
+its client ID and secret in the host's secret manager. The package exports an expiry-aware provider
+that caches Linear's 30-day app-actor token in memory, coalesces concurrent exchanges, renews five
+minutes before expiry, and can be forced to renew after a `401`:
+
+```ts
+import { ClientCredentialsTokenProvider } from "linear-sdk-cli";
+
+const { LINEAR_CLIENT_ID: clientId, LINEAR_CLIENT_SECRET: clientSecret, ...childEnv } = process.env;
+if (!clientId || !clientSecret) throw new Error("Linear OAuth credentials are missing");
+
+const tokens = new ClientCredentialsTokenProvider({
+  clientId,
+  clientSecret,
+  scopes: ["read", "write"],
+});
+
+const { accessToken } = await tokens.getAccessToken();
+const child = Bun.spawn(["linear", "issue", "list", "--json"], {
+  env: { ...childEnv, LINEAR_ACCESS_TOKEN: accessToken },
+});
+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.
+
+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
+remains distinct from this CLI's browser PKCE login for a human `actor=user`.
+
+For a distinct app identity, install the OAuth application with `actor=app`. Native Linear agents
+can additionally request `app:mentionable` and `app:assignable` and subscribe to Agent Session
+webhooks. App actors cannot request the `admin` scope. See Linear's
+[OAuth guide](https://linear.app/developers/oauth-2-0-authentication),
+[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.
 
 ### Multiple workspaces
 
-Credentials are stored per **workspace slug**. `auth login` validates the key and derives the slug
-from the key's organization unless you pass `--workspace`:
+Credentials are stored per **workspace slug**. Browser and API-key login both derive the slug from
+the authenticated organization; `--workspace` validates that the result matches:
 
 ```sh
-linear auth login --workspace acme         # store a key for the "acme" workspace
-linear auth login --workspace other-org    # …and another
+linear auth login --workspace acme         # browser OAuth for "acme"
+linear auth login --workspace other-org    # …and another workspace
+linear auth login --workspace acme --key - # personal API-key fallback via stdin
 linear auth list                           # show configured workspaces + which is default
 linear auth default acme                   # choose the default workspace
 linear --workspace other-org issue list    # use a specific workspace for one command
-linear auth logout --workspace acme        # remove one credential
+linear auth logout --workspace acme        # revoke OAuth, then remove one credential
 ```
 
-**Selection precedence** (strict): the `--api-key` flag and `LINEAR_API_KEY` env are absolute and
-bypass selection entirely; otherwise the workspace is chosen by `--workspace` → `LINEAR_WORKSPACE`
-env → project config `workspace` → `default_workspace` in the user config. With one configured
-workspace it's used automatically; with several and no selection, the CLI asks you to pick (via
-`--workspace`, project config, or `auth default`).
+If revocation is intentionally unavailable, `auth logout --local-only` removes only local state.
+If browser login temporarily superseded an existing personal API-key profile for that workspace,
+OAuth logout preserves and reactivates the API key instead of deleting it.
+
+**Selection precedence** (strict): an explicit `--api-key` or `--access-token` flag bypasses the
+environment and workspace selection entirely. Otherwise `LINEAR_API_KEY` or
+`LINEAR_ACCESS_TOKEN` is absolute. With no invocation-scoped credential, the workspace is chosen
+by `--workspace` → `LINEAR_WORKSPACE` env → project config `workspace` → `default_workspace` in the
+user config. With one configured workspace it's used automatically; with several and no selection,
+the CLI asks you to pick (via `--workspace`, project config, or `auth default`).
 
 ## Core concepts
 
@@ -475,8 +557,9 @@ keyring = true                 # secret lives in the OS keyring (service linear-
 api_key = "lin_api_yyyyyyyy"   # …or, with `auth login --plaintext`, in this 0600 file
 ```
 
-Relevant environment variables: **`LINEAR_API_KEY`** (absolute — bypasses workspace selection) and
-**`LINEAR_WORKSPACE`** (selects a stored credential when no flag is given).
+Relevant environment variables: **`LINEAR_API_KEY`** or **`LINEAR_ACCESS_TOKEN`** (absolute —
+bypasses workspace selection) and **`LINEAR_WORKSPACE`** (selects a stored API-key credential when
+no invocation-scoped credential is given).
 
 ### Shell completion
 
@@ -524,6 +607,7 @@ await createProgram().parseAsync(["node", "linear", "issue", "list", "--json"]);
 bun run verify           # typecheck + lint + unit/contract tests
 bun run test:live        # live integration tests (needs LINEAR_API_KEY + LINEAR_CLI_LIVE=1)
 bun run test:live:admin  # also runs admin-tier suites (e.g. team create/update)
+bun run audit:changelog  # verify package, tag, and generated release-note history
 bun run audit:coverage   # regenerate COVERAGE.md (add --update to re-baseline the snapshot)
 bun run janitor          # sweep leaked `clitest-` fixtures from the test workspace
 ```
@@ -532,6 +616,11 @@ Architecture is three layers — **commands** (commander wiring) → **services*
 resource, the only place that touches the SDK) → **`@linear/sdk`**. The machine JSON envelope is
 locked and contract-tested so output never silently drifts.
 
+Release Please owns `CHANGELOG.md`. Pull requests use Conventional Commit titles and are squash
+merged, giving each change one release-note entry. Do not edit the changelog in a feature or fix
+pull request; use a `BEGIN_COMMIT_OVERRIDE` block in the pull request body when a change needs
+several or specially worded release notes.
+
 > Live integration tests run against a real workspace and share one API key; running the entire
 > suite repeatedly can hit Linear's rate limit. Run a subset (a few files at a time) or re-run
 > after a short pause if you see transient rate-limit failures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",
@@ -61,8 +61,10 @@
     "test:contract": "bun test test/contract",
     "test:live": "LINEAR_CLI_LIVE=1 bun test --timeout 60000 test/integration",
     "test:live:admin": "LINEAR_CLI_LIVE=1 LINEAR_CLI_LIVE_ADMIN=1 bun test --timeout 60000 test/integration",
-    "verify": "bun run typecheck && bun run lint && bun run audit:coverage && bun run format:check && bun run test",
+    "verify": "bun run typecheck && bun run lint && bun run audit:changelog && bun run audit:coverage && bun run format:check && bun run test",
     "skill:docs": "bun run skills/linear-sdk-cli/scripts/generate-docs.ts",
+    "audit:changelog": "bun run scripts/changelog-audit.ts",
+    "audit:pr-title": "bun run scripts/pr-title-audit.ts",
     "audit:coverage": "bun run scripts/coverage-audit.ts",
     "janitor": "bun run test/janitor.ts"
   },
@@ -77,7 +79,7 @@
   "packageManager": "bun@1.4.0",
   "devDependencies": {
     "@types/bun": "^1.4.0",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
     "typescript": "^7.0.2"

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

@@ -35,23 +35,57 @@ lin --version
 
 ### Authentication
 
-The CLI needs a Linear API key. Three ways to provide one, in order of precedence:
+The CLI supports distinct human, hosted-app, and personal-key lifecycles:
 
-1. **`--api-key <key>`** flag (per invocation) or **`LINEAR_API_KEY`** env var — best
+1. **Human browser OAuth (default)** via Authorization Code + PKCE S256, `actor=user`:
+
+   ```bash
+   linear auth login                    # opens Linear; read + write scopes
+   linear auth login --read-only        # read scope only
+   linear auth login --no-browser       # prints URL; loopback callback still required
+   ```
+
+   The CLI validates the viewer/workspace and stores the access token, rotating refresh token,
+   expiry, scopes, client identity, and workspace identity only in the OS keyring. It refreshes
+   before expiry and once after an authentication failure. `--admin` is explicit; no client secret
+   is embedded. `auth logout` revokes this grant before removing it (`--local-only` skips
+   revocation). Remote/headless callers need the loopback host reachable; Linear has no documented
+   device-code flow.
+
+2. **Invocation OAuth access token** via `--access-token <token>` or `LINEAR_ACCESS_TOKEN` — use
+   this for hosted Linear apps, agents, and service accounts. Prefer the environment variable so
+   the secret does not appear in argv:
+
+   ```bash
+   LINEAR_ACCESS_TOKEN=... linear whoami --json
+   ```
+
+   The host application owns OAuth installation, token refresh/client-credentials exchange,
+   client-secret storage, and webhooks. These tokens remain invocation-scoped.
+   Long-lived hosts can import `ClientCredentialsTokenProvider` from `linear-sdk-cli`; it caches
+   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.
+
+3. **`--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
    ```
 
-2. **Stored credentials** via `linear auth login` (validates the key and saves it):
+4. **Stored personal API-key credentials** via the explicit compatibility path:
 
    ```bash
-   linear auth login --key lin_api_...        # non-interactive
-   linear auth login                          # prompts for the key (interactive only)
+   printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -
    ```
 
-3. **Multiple workspaces** — store several credentials and select one per call with
+   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
    `--workspace <slug>`; set a default with `linear auth default <slug>`:
 
    ```bash
@@ -60,8 +94,9 @@ The CLI needs a Linear API key. Three ways to provide one, in order of precedenc
    linear issue list --workspace acme --json
    ```
 
-Inspect resolution with `linear auth status`. Get the resolved key for scripting
-(e.g. raw `curl`) with `linear auth token`.
+An explicit credential flag overrides environment credentials. If both credential kinds occur at
+the same precedence level, the CLI fails rather than silently choosing an actor. Inspect resolution
+with `linear auth status`. `linear auth token` exports stored API keys only and never OAuth tokens.
 
 ## Agent best practices
 

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

@@ -4,7 +4,7 @@
 
 _Generated from `linear commands --json`. `linear api --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear api`
 

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

@@ -6,7 +6,7 @@ Group alias: `at`
 
 _Generated from `linear commands --json`. `linear attachment --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear attachment`
 

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

@@ -4,7 +4,7 @@
 
 _Generated from `linear commands --json`. `linear auth --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear auth`
 
@@ -63,29 +63,39 @@ linear auth list [options]
 ```text
 slug: string
 isDefault: boolean
+credentialType: string
 storage: string
 ```
 
 ### `linear auth login`
 
-Validate and store a Linear API key for a workspace
+Authenticate in the browser with OAuth, or store a personal API key
 
 ```
 linear auth login [options]
 ```
 
-| Option        | Description                                                           |
-| ------------- | --------------------------------------------------------------------- |
-| `--key <key>` | API key (otherwise prompted; '-' reads it from stdin)                 |
-| `--plaintext` | Store the key in the config file (0600) instead of the system keyring |
+| Option                 | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| `--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                                 |
 
 **Output (`--json`)**: a receipt object
 
 ```text
 success: boolean
+credentialType: string
 workspace: string
 user: {id: string, name: string, email: string}
 storage: string
+scopes?: string[]
+expiresAt?: string
 path: string
 ```
 
@@ -97,12 +107,18 @@ Remove a stored workspace credential (select with --workspace <slug>)
 linear auth logout [options]
 ```
 
+| Option         | Description                                       |
+| -------------- | ------------------------------------------------- |
+| `--local-only` | remove local credentials without OAuth revocation |
+
 **Output (`--json`)**: a receipt object
 
 ```text
 success: boolean
 workspace: string
 removed: boolean
+revocation: string
+fallbackCredentialType: string | null
 ```
 
 ### `linear auth migrate`
@@ -123,7 +139,7 @@ path: string
 
 ### `linear auth status`
 
-Show where the API key is resolved from (key redacted)
+Show where the active credential is resolved from (value redacted)
 
 ```
 linear auth status [options]
@@ -133,10 +149,13 @@ linear auth status [options]
 
 ```text
 authenticated: boolean
+credentialType: string | null
 source: string
 workspace: string | null
 key: string
 keyring: string | null
+scopes: string[] | null
+expiresAt: string | null
 ```
 
 ### `linear auth token`

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

@@ -4,7 +4,7 @@
 
 _Generated from `linear commands --json`. `linear commands --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear commands`
 

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

@@ -6,7 +6,7 @@ Group alias: `cm`
 
 _Generated from `linear commands --json`. `linear comment --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear comment`
 

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

@@ -4,7 +4,7 @@
 
 _Generated from `linear commands --json`. `linear completion --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear completion`
 

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

@@ -4,7 +4,7 @@
 
 _Generated from `linear commands --json`. `linear config --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear config`
 
@@ -19,6 +19,8 @@ linear config [options]
 ```text
 apiKey: string
 apiKeySource: string
+accessToken: string
+accessTokenSource: string
 credentialWorkspace: string | null
 team: string | null
 workspace: string | null
@@ -88,6 +90,8 @@ linear config show [options]
 ```text
 apiKey: string
 apiKeySource: string
+accessToken: string
+accessTokenSource: string
 credentialWorkspace: string | null
 team: string | null
 workspace: string | null

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

@@ -6,7 +6,7 @@ Group alias: `c`
 
 _Generated from `linear commands --json`. `linear cycle --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear cycle`
 

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

@@ -6,7 +6,7 @@ Group alias: `doc`
 
 _Generated from `linear commands --json`. `linear document --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear document`
 

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

@@ -6,7 +6,7 @@ Group alias: `fav`
 
 _Generated from `linear commands --json`. `linear favorite --help` (or `<subcommand> --help`) is authoritative._
 
-Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
 
 ### `linear favorite`