linear-sdk-cli 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.9.1](https://github.com/zhendalf/linear-sdk-cli/compare/v0.9.0...v0.9.1) (2026-10-22)
+
+### Bug Fixes
+
+- **auth:** default to personal API-key login ([#98](https://github.com/zhendalf/linear-sdk-cli/issues/98)) ([0d57f7c](https://github.com/zhendalf/linear-sdk-cli/commit/0d57f7c741bc5e9099787271cde16f436cb21f13))
+
 ## [0.9.0](https://github.com/zhendalf/linear-sdk-cli/compare/v0.8.3...v0.9.0) (2026-10-22)
 
 ### Features

package/MIGRATING.md

@@ -48,13 +48,21 @@ 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) — 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.
+`linear auth login --key -`, or run bare `linear auth login` for a hidden personal API-key prompt.
+Login requires a system keyring unless you explicitly pass `--plaintext` to use our `0600`
+`config.toml` instead. `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`.
 
+Earlier versions defaulted to browser OAuth through a bundled client ID. That login flow and its
+callback options have been removed. Existing stored OAuth user profiles still refresh and support
+logout/revocation using their saved client ID. For new authentication, use a personal API key,
+`LINEAR_ACCESS_TOKEN` / `--access-token` on commands (the issuing grant determines user/app identity),
+or `auth login --app` with your own client ID and secret. Supplied access tokens remain temporary;
+the CLI does not persist or refresh them. No hardcoded OAuth client ID is shipped.
+
 ## 3. Config — same files, same keys
 
 We look in every place schpet does, in its order. Walking up from the working directory, each

package/README.md

@@ -70,9 +70,9 @@ retains their best ideas and provides a careful compatibility and migration path
 
 ## Install
 
-Requires [Bun](https://bun.sh) **1.1 or newer**. Authenticate with browser OAuth (the default), an
-invocation-scoped OAuth access token, or a personal API key. The CLI ships as TypeScript and runs
-directly on Bun — no build step, no bundle, no Node.
+Requires [Bun](https://bun.sh) **1.1 or newer**. Authenticate with a personal API key (the default),
+an invocation-scoped OAuth access token, or your app's client credentials. The CLI ships as
+TypeScript and runs directly on Bun — no build step, no bundle, no Node.
 
 ```sh
 bun add --global linear-sdk-cli
@@ -103,7 +103,7 @@ bun run src/bin/linear.ts --help     # or: bun run dev -- --help
 ## Quickstart
 
 ```sh
-linear auth login                          # browser OAuth; or set LINEAR_API_KEY
+linear auth login                          # securely prompt for a personal API key
 linear whoami                              # confirm you're connected
 
 linear issue list --assignee me --state started        # my in-progress work
@@ -118,9 +118,12 @@ branch, so most issue commands let you omit the id entirely.
 
 ## Authentication
 
-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;
+For a person at a terminal, `linear auth login` prompts for a personal API key without echoing it.
+Create a key in [Security & Access](https://linear.app/settings/account/security), choosing its
+permissions and team access there. Workspace administrators may restrict member key creation.
+No OAuth application installation, bundled client ID, or browser callback is required.
+
+For commands, explicit `--api-key` or `--access-token` flags override environment credentials;
 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;
@@ -129,14 +132,13 @@ 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.
 > A project may select one of your already-stored credentials with `workspace = "<slug>"`, but it
-> 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.
+> cannot provide or override the secret. Existing browser OAuth credentials remain keyring-only;
+> a 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 login                          # hidden personal API-key prompt
+printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -  # explicit stdin input
+linear auth login --app --client-id YOUR_CLIENT_ID --client-secret -
 linear auth status                         # credential kind and source (value redacted)
 linear auth logout --workspace acme        # revoke OAuth (if used) and remove the profile
 ```
@@ -148,30 +150,27 @@ Linear provides no safe read-only scope introspection for them. `whoami --json`
 member's workspace role in `admin` and reports credential authorization separately under
 `authorization`; an admin member can still hold a credential that lacks the `admin` scope.
 
-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 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
-API-key-only compatibility option. API-key entries use `account = <workspace slug>`, preserving
-compatibility with existing keyring profiles. 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.
+Both the prompt and `auth login --key -` validate the viewer/workspace before storing the key in
+the system keyring (`service = linear-cli`, `account = <workspace slug>`), with only a marker in
+the user config. If there is no system keyring, login requires explicit `--plaintext` to store
+API-key or app credentials in the private user config (`0600`). Passing `--key <value>` also works
+but warns because argv and shell history expose it. `auth migrate` moves legacy plaintext keys
+into the keyring; `auth token` exports stored API keys only, never OAuth tokens.
+
+JSON, `--no-input`, and redirected sessions never prompt. Supply `--key -` explicitly for stdin;
+bare login does not import environment credentials. To authenticate a command without saving
+credentials, set `LINEAR_API_KEY` or `LINEAR_ACCESS_TOKEN` instead. `--read-only` and `--scope`
+apply only to `--app`; set personal API-key permissions in Linear when creating the key.
+
+Browser login and its `--no-browser`, `--redirect-uri`, `--timeout`, and `--admin` options have
+been removed. Existing stored OAuth user profiles still refresh using their own saved client ID,
+retain scope reporting, and support revocation on logout. No embedded client ID is needed to use
+these profiles. New personal logins use API keys.
 
 ### Apps, agents, and service accounts
 
-Use an OAuth access token when the CLI runs inside an integration or agent:
+Use an OAuth access token when the CLI runs inside an integration or agent. The token may
+represent a user or app; its issuing grant determines the identity and permissions:
 
 ```sh
 LINEAR_ACCESS_TOKEN="$access_token" linear whoami --json
@@ -256,7 +255,7 @@ access to the same user config. Switching storage removes the previous copy of t
 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
+(default: `read,write`). App actors cannot request 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.
 
@@ -280,13 +279,13 @@ disable the app in Linear. Environment-only credentials must be unset separately
 
 ### Multiple workspaces
 
-Credentials are stored per **workspace slug**. Browser, app, and API-key login derive the slug from
+Credentials are stored per **workspace slug**. App and API-key login derive the slug from
 the authenticated organization; `--workspace` validates that the result matches:
 
 ```sh
-linear auth login --workspace acme         # browser OAuth for "acme"
+linear auth login --workspace acme         # prompt for an API key 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 login --workspace acme --key - # personal API key via stdin
 linear auth list                           # show configured workspaces + which is default
 linear auth default acme                   # choose the default workspace
 linear config set team ENG --user --workspace acme # set its validated default team
@@ -294,7 +293,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, 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.
+Successful 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.9.0",
+  "version": "0.9.1",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",

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

@@ -35,22 +35,24 @@ lin --version
 
 ### Authentication
 
-The CLI supports distinct human, hosted-app, and personal-key lifecycles:
+The CLI supports personal API keys, supplied access tokens, and app credentials. No client ID
+is bundled, and new login never starts browser OAuth:
 
-1. **Human browser OAuth (default)** via Authorization Code + PKCE S256, `actor=user`:
+1. **Personal API key (default)**:
 
    ```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
+   linear auth login                    # hidden API-key prompt in an interactive terminal
+   printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -
    ```
 
-   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.
+   Create a key at https://linear.app/settings/account/security, choosing permissions and team
+   access in Linear; workspace policy may restrict member key creation. Never ask for a key in
+   chat. The CLI validates the viewer/workspace before storing it in the OS keyring. If no keyring
+   is available, login requires explicit `--plaintext` for private user-config storage (`0600`).
+   Passing `--key <value>` also works but exposes the key in argv and produces a warning.
+   JSON, `--no-input`, and redirected sessions never prompt; use explicit `--key -` for stdin.
+   Bare login does not import environment credentials. `--read-only` and `--scope` require
+   `--app`; they cannot restrict an existing personal API key.
 
 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
@@ -60,6 +62,7 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
    LINEAR_ACCESS_TOKEN=... linear whoami --json
    ```
 
+   Tokens may represent a user or app; their issuing grant determines identity and permissions.
    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
@@ -102,16 +105,7 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
    LINEAR_API_KEY=lin_api_... linear whoami --json
    ```
 
-5. **Stored personal API-key credentials** via the explicit compatibility path:
-
-   ```bash
-   printf '%s\n' "$LINEAR_API_KEY" | linear auth login --key -
-   ```
-
-   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.
-
-6. **Multiple workspaces** — store several OAuth or API-key credentials and select one per call with
+5. **Multiple workspaces** — store several app or API-key credentials and select one per call with
    `--workspace <slug>`; set a default with `linear auth default <slug>`:
 
    ```bash
@@ -120,6 +114,11 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
    linear issue list --workspace acme --json
    ```
 
+Existing stored OAuth user profiles remain supported: their own saved client ID is used for
+refresh, scope reporting is retained, and logout revokes the grant (`--local-only` skips
+revocation). New browser login and its `--no-browser`, `--redirect-uri`, `--timeout`, and `--admin`
+options have been removed. Do not tell users to register or install a CLI OAuth application.
+
 Login associates the authenticated workspace with the discovered project config, or creates `.linear.toml` at the Git root (cwd outside Git). Use `--no-project` for credential-only login; JSON reports `projectConfigPath` or null. Credentials stay global. Workspace selection is `--workspace` → `LINEAR_WORKSPACE` → project config → optional global default. A sole stored workspace is automatic; multiple unselected workspaces prompt only interactively and fail in JSON/noninteractive mode. Login/adoption/logout never assign a new default. Existing legacy defaults remain valid because their original intent is unknown; `auth default` is an explicit convenience.
 
 When a workspace URL slug changes, use `linear auth rename <old-slug> <new-slug> --json`

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

@@ -69,7 +69,7 @@ storage: string
 
 ### `linear auth login`
 
-Authenticate and select the workspace for this project
+Sign in with a personal API key (default) or app credentials
 
 ```
 linear auth login [options]
@@ -80,16 +80,12 @@ linear auth login [options]
 | `--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                               |
+| `--read-only`              | request read-only access with --app                                     |
 | `--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                                   |
+| `--client-id <id>`         | app client ID (defaults to LINEAR_CLIENT_ID)                            |
 
 **Output (`--json`)**: a receipt object
 
@@ -99,8 +95,6 @@ credentialType: string
 workspace: string
 user: {id: string, name: string, email: string}
 storage: string
-scopes?: string[]
-expiresAt?: string
 path: string
 projectConfigPath: string | null
 ```

package/src/commands/meta.ts

@@ -18,7 +18,6 @@ import {
   setDefaultWorkspace,
   listCredentials,
   readOAuthCredential,
-  writeOAuthCredential,
   migrateCredentials,
   renameApiKeyProfile,
   profileRenameProjectUpdates,
@@ -35,12 +34,11 @@ import {
 import { keyring } from "../lib/keyring.js";
 import { readStdinSync } from "../lib/body.js";
 import { CliError, authError, normalizeError, usageError } from "../lib/errors.js";
-import { confirmDestructive, promptSelect } from "../lib/prompt.js";
+import { confirmDestructive, promptSecret, promptSelect } from "../lib/prompt.js";
 import { listTeams } from "../services/team.js";
 import { resolveTeam } from "../lib/resolve.js";
 import { ISSUE_SORTS } from "../services/issue.js";
 import { firstTeam, type Context } from "../context.js";
-import { openUrl } from "../lib/open.js";
 import {
   authorizationCapabilities,
   credentialType as resolvedCredentialType,
@@ -48,19 +46,9 @@ import {
 import {
   ClientCredentialsTokenProvider,
   clientCredentialsScopes,
-  DEFAULT_OAUTH_SCOPES,
-  buildAuthorizationUrl,
-  createPkceRequest,
-  exchangeAuthorizationCode,
   revokeOAuthToken,
-  startLoopbackCallback,
-  type OAuthUserCredential,
 } from "../oauth.js";
 
-export const DEFAULT_OAUTH_REDIRECT_URI = "http://127.0.0.1:43821/oauth/callback";
-/** Public PKCE client identity. This is not a credential; no client secret is shipped or used. */
-export const DEFAULT_OAUTH_CLIENT_ID = "eda60862e4bb8b8af82cfb3193b65c2f";
-
 /**
  * The `whoami` handler, shared by the top-level `linear whoami` and the
  * reference CLI's spelling `linear auth whoami` so the two cannot drift.
@@ -113,6 +101,12 @@ const defaultAuthValidationClientFactory: AuthValidationClientFactory = (credent
     kind === "oauth-access-token" ? { accessToken: credential } : { apiKey: credential },
   ) as unknown as AuthValidationClient;
 let authValidationClientFactory = defaultAuthValidationClientFactory;
+let authSecretPrompt = promptSecret;
+
+/** Test seam that does not depend on Bun's module-namespace spying behavior. */
+export function setAuthSecretPromptForTests(prompt: typeof promptSecret | undefined): void {
+  authSecretPrompt = prompt ?? promptSecret;
+}
 
 /** Test seam for command-level auth tests; production always uses LinearClient. */
 export function setAuthValidationClientFactoryForTests(
@@ -231,17 +225,14 @@ export function registerMeta(program: Command): void {
   // login -------------------------------------------------------------------
   auth
     .command("login")
-    .description("Authenticate and select the workspace for this project")
+    .description("Sign in with a personal API key (default) or app credentials")
     .option("--no-project", "save credentials without changing the project workspace")
     .option("--key <key>", "use a personal API key ('-' reads it from stdin)")
     .option(
       "--plaintext",
       "Store API-key or app credentials in the private user config file (0600)",
     )
-    .option("--no-browser", "print the authorization URL instead of opening it")
-    .option("--read-only", "request read-only OAuth access")
-    .option("--admin", "explicitly add the OAuth admin scope")
-    .option("--timeout <seconds>", "seconds to wait for the loopback callback", "120")
+    .option("--read-only", "request read-only access with --app")
     .option("--app", "sign in as an app using client credentials")
     .option("--client-credentials", "alias for --app")
     .option("--scope <scopes>", "comma-separated app scopes (default: read,write)")
@@ -249,30 +240,18 @@ export function registerMeta(program: Command): void {
       "--client-secret <secret>",
       "app client secret ('-' reads stdin; defaults to LINEAR_CLIENT_SECRET)",
     )
-    .option(
-      "--client-id <id>",
-      "OAuth client ID (app: LINEAR_CLIENT_ID; browser: packaged CLI app)",
-    )
-    .option("--redirect-uri <uri>", "registered HTTP loopback callback URI")
+    .option("--client-id <id>", "app client ID (defaults to LINEAR_CLIENT_ID)")
     .action(
       action(async (ctx: Context, opts) => {
         if (ctx.options.accessToken !== undefined) {
           throw usageError(
-            "`auth login` cannot persist an injected access token. Remove --access-token and use browser OAuth, or use --key - for a personal API key.",
+            "`auth login` cannot persist an injected access token. Use LINEAR_ACCESS_TOKEN or --access-token with a data command, or use `auth login --key -` for a personal API key.",
           );
         }
         if (opts.app || opts.clientCredentials) {
-          if (
-            opts.key !== undefined ||
-            ctx.options.apiKey !== undefined ||
-            opts.redirectUri ||
-            opts.browser === false
-          ) {
-            throw usageError(
-              "--app cannot be combined with personal API-key or browser callback options.",
-            );
+          if (opts.key !== undefined || ctx.options.apiKey !== undefined) {
+            throw usageError("--app cannot be combined with --key or --api-key.");
           }
-          if (opts.admin) throw usageError("App actors cannot request the admin scope.");
           if (!opts.plaintext && !keyring())
             throw new CliError(
               "App authentication requires a system keyring; use --plaintext for explicit private-file storage.",
@@ -337,144 +316,64 @@ export function registerMeta(program: Command): void {
           );
           return;
         }
-        if (opts.clientSecret !== undefined || opts.scope !== undefined)
-          throw usageError("--client-secret and --scope require --app or --client-credentials.");
+        if (
+          opts.clientId !== undefined ||
+          opts.clientSecret !== undefined ||
+          opts.scope !== undefined ||
+          opts.readOnly
+        )
+          throw usageError(
+            "--client-id, --client-secret, --scope, and --read-only require --app or --client-credentials. Set personal API-key permissions in Linear's Security & Access settings.",
+          );
         let key: string | undefined = selectLoginKey(opts.key, ctx.options.apiKey);
-        if (key !== undefined) {
-          if (
-            opts.readOnly ||
-            opts.admin ||
-            opts.browser === false ||
-            opts.redirectUri ||
-            opts.clientId
-          ) {
-            throw usageError("OAuth-only options cannot be combined with --key or --api-key.");
-          }
+        if (key === undefined && !ctx.isTTY)
+          throw usageError(
+            "Personal API-key login requires interactive input. Pipe a key to `linear auth login --key -`, or use --app for app credentials. To authenticate commands without saving credentials, set LINEAR_API_KEY or LINEAR_ACCESS_TOKEN.",
+          );
+        if (!opts.plaintext && !keyring())
+          throw new CliError(
+            "API-key login requires a system keyring; use --plaintext for explicit private-file storage.",
+            "runtime",
+          );
+        if (key === undefined) {
+          ctx.output.info(
+            "Create a personal API key at https://linear.app/settings/account/security. Choose its permissions and team access in Linear; workspace policy may restrict key creation.",
+          );
+          key = await authSecretPrompt(ctx, "Linear API key:", { required: true });
+        } else {
           if (key === "-") key = readStdinSync();
           else
             ctx.output.warn(
               "An API key on the command line is visible to other processes and shell history; prefer --key - (stdin).",
             );
-          key = key.trim();
-          if (!key) throw usageError("No API key provided.");
-          const identity = await validateAuthCredential(key, ctx.options.workspace);
-          const { user: me, organization: org } = identity;
-          const { path, storage, keyringLabel } = writeCredential(org.urlKey, key, {
-            plaintext: opts.plaintext === true,
-          });
-          const projectConfigPath = saveLoginProject(ctx, org.urlKey, opts.project !== false);
-          const where =
-            storage === "keychain"
-              ? `Credential saved to the ${keyringLabel}; ${path} records the workspace.`
-              : `Credential saved to ${path} (plaintext, 0600).`;
-          ctx.output.emit(
-            {
-              success: true,
-              credentialType: "api-key",
-              workspace: org.urlKey,
-              user: me,
-              storage,
-              path,
-              projectConfigPath,
-            },
-            () =>
-              ctx.output.success(
-                `Authenticated as ${me.name} <${me.email}> for workspace '${org.urlKey}'. ${where}${projectConfigPath ? ` Project workspace saved to ${projectConfigPath}.` : ""}`,
-              ),
-          );
-          return;
         }
-
-        if (opts.plaintext) {
-          throw usageError(
-            "Browser OAuth is keyring-only; --plaintext requires --key, --api-key, or --client-credentials.",
-          );
-        }
-        if (opts.readOnly && opts.admin) {
-          throw usageError("--read-only cannot be combined with --admin.");
-        }
-        const timeoutSeconds = Number(opts.timeout);
-        if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
-          throw usageError("--timeout must be a positive number of seconds.");
-        }
-        const clientId = String(
-          opts.clientId ?? process.env.LINEAR_OAUTH_CLIENT_ID ?? DEFAULT_OAUTH_CLIENT_ID,
-        ).trim();
-        const redirectUri = String(
-          opts.redirectUri ?? process.env.LINEAR_OAUTH_REDIRECT_URI ?? DEFAULT_OAUTH_REDIRECT_URI,
-        );
-        const scopes = opts.readOnly
-          ? ["read"]
-          : opts.admin
-            ? [...DEFAULT_OAUTH_SCOPES, "admin"]
-            : [...DEFAULT_OAUTH_SCOPES];
-        const pkce = createPkceRequest();
-        const callback = await startLoopbackCallback({
-          redirectUri,
-          state: pkce.state,
-          timeoutMs: timeoutSeconds * 1000,
+        key = key.trim();
+        if (!key) throw usageError("No API key provided.");
+        const identity = await validateAuthCredential(key, ctx.options.workspace);
+        const { user: me, organization: org } = identity;
+        const { path, storage, keyringLabel } = writeCredential(org.urlKey, key, {
+          plaintext: opts.plaintext === true,
         });
-        try {
-          const authorizationUrl = buildAuthorizationUrl({
-            clientId,
-            redirectUri: callback.redirectUri,
-            scopes,
-            challenge: pkce.challenge,
-            state: pkce.state,
-          });
-          if (opts.browser === false) {
-            ctx.output.info(`Open this URL to authenticate with Linear:\n${authorizationUrl}`);
-          } else {
-            ctx.output.info("Opening Linear in your browser…");
-            await openUrl(authorizationUrl);
-          }
-          const code = await callback.wait;
-          const token = await exchangeAuthorizationCode({
-            code,
-            verifier: pkce.verifier,
-            clientId,
-            redirectUri: callback.redirectUri,
-          });
-          const identity = await validateAuthCredential(
-            token.accessToken,
-            ctx.options.workspace,
-            "oauth-access-token",
-          );
-          const credential: OAuthUserCredential = {
-            version: 1,
-            kind: "oauth-user",
-            actor: "user",
-            ...token,
-            clientId,
-            workspace: identity.organization,
-            user: identity.user,
-          };
-          const saved = writeOAuthCredential(credential);
-          const projectConfigPath = saveLoginProject(
-            ctx,
-            credential.workspace.urlKey,
-            opts.project !== false,
-          );
-          ctx.output.emit(
-            {
-              success: true,
-              credentialType: "oauth-user",
-              workspace: credential.workspace.urlKey,
-              user: credential.user,
-              storage: saved.storage,
-              scopes: credential.scopes,
-              expiresAt: new Date(credential.expiresAt).toISOString(),
-              path: saved.path,
-              projectConfigPath,
-            },
-            () =>
-              ctx.output.success(
-                `Authenticated as ${credential.user.name} <${credential.user.email}> for workspace '${credential.workspace.urlKey}'. OAuth credentials saved to the ${saved.keyringLabel}.${projectConfigPath ? ` Project workspace saved to ${projectConfigPath}.` : ""}`,
-              ),
-          );
-        } finally {
-          await callback.close();
-        }
+        const projectConfigPath = saveLoginProject(ctx, org.urlKey, opts.project !== false);
+        const where =
+          storage === "keychain"
+            ? `Credential saved to the ${keyringLabel}; ${path} records the workspace.`
+            : `Credential saved to ${path} (plaintext, 0600).`;
+        ctx.output.emit(
+          {
+            success: true,
+            credentialType: "api-key",
+            workspace: org.urlKey,
+            user: me,
+            storage,
+            path,
+            projectConfigPath,
+          },
+          () =>
+            ctx.output.success(
+              `Authenticated as ${me.name} <${me.email}> for workspace '${org.urlKey}'. ${where}${projectConfigPath ? ` Project workspace saved to ${projectConfigPath}.` : ""}`,
+            ),
+        );
       }),
     );
 

package/src/config.ts

@@ -14,10 +14,10 @@
  *  - Authentication secrets have a STRICTER boundary and are never read from a project file
  *    or from the reference CLI's global file (avoids committing secrets):
  *    Explicit `--access-token` / `--api-key` flags override their environment counterparts.
- *    Invocation OAuth access tokens are stateless (`LINEAR_ACCESS_TOKEN` only). Human browser
- *    OAuth sessions, app client credentials, and API keys may come from the OS keyring.
- *    App credentials require explicit --plaintext to use a private user config file;
- *    browser OAuth stays keyring-only. Environment client credentials stay invocation-scoped.
+ *    Invocation OAuth access tokens are stateless (`LINEAR_ACCESS_TOKEN` / --access-token).
+ *    Existing OAuth user sessions, app client credentials, and API keys may come from the OS keyring.
+ *    New login requires explicit --plaintext to use a private user config file;
+ *    existing browser OAuth stays keyring-only. Environment client credentials stay invocation-scoped.
  *    A project `workspace` may select which already-stored credential to use;
  *    it can never provide or override the secret itself.
  *
@@ -1443,7 +1443,7 @@ export function writeOAuthCredential(credential: OAuthUserCredential): WriteOAut
   const backend = keyring();
   if (!backend) {
     throw new CliError(
-      "Browser OAuth requires a usable system keyring; use `linear auth login --key -` on this platform.",
+      "Stored OAuth sessions require a usable system keyring; use `linear auth login --key - --plaintext` for a personal API key on this platform.",
       "runtime",
     );
   }
@@ -1540,7 +1540,7 @@ export function probeKeyringCredential(slug: string): KeyringCredentialProbe {
   const backend = keyring();
   if (!backend) {
     throw new CliError(
-      `No usable system keyring is available, so workspace '${sanitize(slug)}' cannot be adopted. Run \`linear auth login --key -\` to read the key from stdin instead.`,
+      `No usable system keyring is available, so workspace '${sanitize(slug)}' cannot be adopted. Run \`linear auth login --key - --plaintext\` to read the key from stdin into the private user config instead.`,
       "runtime",
     );
   }

package/src/lib/authorization.ts

@@ -76,7 +76,7 @@ export function enrichAuthorizationError(error: unknown, config: ResolvedConfig)
   const capabilities = authorizationCapabilities(config);
   const remediation =
     capabilities.credentialType === "oauth-user"
-      ? "Re-authenticate with `linear auth login --admin`; member admin status alone is insufficient."
+      ? "Create a personal API key with admin permission in Linear's Security & Access settings, then run `linear auth login`; member admin status alone is insufficient."
       : "Use a credential authorized for the admin scope; member admin status alone is insufficient.";
   return new CliError(
     normalized.message,

package/src/lib/keyring.ts

@@ -10,8 +10,8 @@
  * Backends are synchronous (spawnSync) because config resolution is
  * synchronous and runs before any command body. Only macOS Keychain and the
  * Linux Secret Service (`secret-tool`) are implemented; everywhere else — and
- * wherever the tool is missing — `keyring()` returns null and the callers fall
- * back to the plaintext file without complaint.
+ * wherever the tool is missing — `keyring()` returns null. Login requires explicit
+ * --plaintext for private-file storage; low-level legacy API-key writers can fall back.
  *
  * The secret never travels on argv (visible to every process via `ps`): on
  * macOS it goes through `security -i`, which reads its command line from stdin;

package/src/lib/output-shapes.ts

@@ -391,8 +391,6 @@ export const OUTPUT_SHAPES: Record<string, OutputShape | null> = {
     workspace: "string",
     user: { id: "string", name: "string", email: "string" },
     storage: "string",
-    "scopes?": ["string"],
-    "expiresAt?": "string",
     path: "string",
     projectConfigPath: "string|null",
   }),