linear-sdk-cli 0.8.3 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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
+
+- add native release commands and folder project defaults ([#97](https://github.com/zhendalf/linear-sdk-cli/issues/97)) ([e382f52](https://github.com/zhendalf/linear-sdk-cli/commit/e382f52a8146ede0d9268d6c6aa557f9836e9274))
+- **auth:** add resumable workspace API-key profile rename ([#95](https://github.com/zhendalf/linear-sdk-cli/issues/95)) ([9297b16](https://github.com/zhendalf/linear-sdk-cli/commit/9297b16e00928441124bffe291a0567e86c59f09))
+
 ## [0.8.3](https://github.com/zhendalf/linear-sdk-cli/compare/v0.8.2...v0.8.3) (2026-10-19)
 
 ### Bug Fixes

package/COVERAGE.md

@@ -4,18 +4,19 @@ Generated by `bun run audit:coverage`. Total LinearClient members: **481**.
 
 | Status   | Count | Meaning                                         |
 | -------- | ----- | ----------------------------------------------- |
-| curated  | 107   | Has a first-class CLI command                   |
+| curated  | 128   | Has a first-class CLI command                   |
 | raw-only | 146   | Reachable via `linear api` (no bespoke command) |
-| excluded | 228   | Out of scope (admin/integration/SDK plumbing)   |
+| excluded | 207   | 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.
 
 ## Curated field capabilities
 
+- Release projections — `ReleasePipeline.stages`, `Release.issues/links`, and release-note document content are selected through the authenticated SDK GraphQL transport, with stable command JSON shapes and offline schema validation.
 - Issue delegation (Developer Preview) — `Issue.delegate`, `IssueCreateInput.delegateId`, `IssueUpdateInput.delegateId`, and eligible agent-user fields are covered by `issue delegate` and the delegation options on `issue create`/`issue update`.
 
-## Curated (107)
+## Curated (128)
 
 - `agentSession` — issue
 - `agentSessions` — issue
@@ -41,9 +42,14 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `createIssue` — issue
 - `createIssueLabel` — label
 - `createIssueRelation` — issue
+- `createIssueToRelease` — release
 - `createProject` — project
 - `createProjectMilestone` — milestone
 - `createProjectUpdate` — project-update
+- `createRelease` — release
+- `createReleaseNote` — release-note
+- `createReleasePipeline` — release-pipeline
+- `createReleaseStage` — release-stage
 - `createRoadmap` — roadmap
 - `createTeam` — team
 - `createWebhook` — webhook
@@ -63,6 +69,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `deleteIssueRelation` — issue
 - `deleteProject` — project
 - `deleteProjectMilestone` — milestone
+- `deleteReleaseNote` — release-note
 - `deleteRoadmap` — roadmap
 - `deleteTeam` — team
 - `deleteWebhook` — webhook
@@ -82,6 +89,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `issueRelations` — issue
 - `issueSearch` — issue
 - `issueSubscribe` — issue
+- `issueToReleaseDeleteByIssueAndRelease` — release
 - `issueUnsubscribe` — issue
 - `issues` — issue
 - `notification` — notification
@@ -96,6 +104,16 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `projectStatuses` — project
 - `projectUpdates` — project-update
 - `projects` — project
+- `release` — release
+- `releaseComplete` — release
+- `releaseNote` — release-note
+- `releaseNotes` — release-note
+- `releasePipeline` — release-pipeline
+- `releasePipelines` — release-pipeline
+- `releaseStage` — release-stage
+- `releaseSync` — release
+- `releaseUpdateByPipeline` — release
+- `releases` — release
 - `roadmap` — roadmap
 - `roadmaps` — roadmap
 - `searchIssues` — issue
@@ -114,6 +132,10 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `updateNotification` — notification
 - `updateProject` — project
 - `updateProjectMilestone` — milestone
+- `updateRelease` — release
+- `updateReleaseNote` — release-note
+- `updateReleasePipeline` — release-pipeline
+- `updateReleaseStage` — release-stage
 - `updateRoadmap` — roadmap
 - `updateTeam` — team
 - `updateWebhook` — webhook
@@ -125,7 +147,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `workflowState` — state
 - `workflowStates` — state
 
-## Excluded (228)
+## Excluded (207)
 
 - `agentActivities` — specialized/raw api only
 - `agentActivity` — specialized/raw api only
@@ -161,14 +183,9 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `createIntegrationGithubCommit` — integration/import (raw api only)
 - `createIntegrationTemplate` — integration/import (raw api only)
 - `createIntegrationsSettings` — integration/import (raw api only)
-- `createIssueToRelease` — specialized/raw api only
 - `createNotificationSubscription` — specialized/raw api only
 - `createOrganizationInvite` — admin/enterprise (raw api only)
 - `createPushSubscription` — specialized/raw api only
-- `createRelease` — specialized/raw api only
-- `createReleaseNote` — specialized/raw api only
-- `createReleasePipeline` — specialized/raw api only
-- `createReleaseStage` — specialized/raw api only
 - `createTemplate` — specialized/raw api only
 - `createTimeSchedule` — specialized/raw api only
 - `createTriageResponsibility` — specialized/raw api only
@@ -207,7 +224,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `deleteOrganizationInvite` — admin/enterprise (raw api only)
 - `deletePushSubscription` — specialized/raw api only
 - `deleteRelease` — specialized/raw api only
-- `deleteReleaseNote` — specialized/raw api only
 - `deleteReleasePipeline` — specialized/raw api only
 - `deleteTemplate` — specialized/raw api only
 - `deleteTimeSchedule` — specialized/raw api only
@@ -276,7 +292,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `issueImportProcess` — integration/import (raw api only)
 - `issueTitleSuggestionFromCustomerRequest` — specialized/raw api only
 - `issueToRelease` — specialized/raw api only
-- `issueToReleaseDeleteByIssueAndRelease` — specialized/raw api only
 - `issueToReleases` — specialized/raw api only
 - `latestReleaseByAccessKey` — specialized/raw api only
 - `logout` — auth/session flows (out of scope)
@@ -291,22 +306,12 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `pushSubscriptionTest` — specialized/raw api only
 - `rateLimitStatus` — SDK plumbing
 - `recentReleasesByAccessKey` — specialized/raw api only
-- `release` — specialized/raw api only
-- `releaseComplete` — specialized/raw api only
 - `releaseCompleteByAccessKey` — specialized/raw api only
-- `releaseNote` — specialized/raw api only
-- `releaseNotes` — specialized/raw api only
-- `releasePipeline` — specialized/raw api only
 - `releasePipelineByAccessKey` — specialized/raw api only
-- `releasePipelines` — specialized/raw api only
 - `releaseSearch` — specialized/raw api only
-- `releaseStage` — specialized/raw api only
 - `releaseStages` — specialized/raw api only
-- `releaseSync` — specialized/raw api only
 - `releaseSyncByAccessKey` — specialized/raw api only
-- `releaseUpdateByPipeline` — specialized/raw api only
 - `releaseUpdateByPipelineByAccessKey` — specialized/raw api only
-- `releases` — specialized/raw api only
 - `samlTokenUserAccountAuth` — auth/session flows (out of scope)
 - `semanticSearch` — specialized/raw api only
 - `slaConfigurations` — specialized/raw api only
@@ -341,10 +346,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `updateIntegrationsSettings` — integration/import (raw api only)
 - `updateIssueImport` — integration/import (raw api only)
 - `updateNotificationSubscription` — specialized/raw api only
-- `updateRelease` — specialized/raw api only
-- `updateReleaseNote` — specialized/raw api only
-- `updateReleasePipeline` — specialized/raw api only
-- `updateReleaseStage` — specialized/raw api only
 - `updateTemplate` — specialized/raw api only
 - `updateTimeSchedule` — specialized/raw api only
 - `updateTriageResponsibility` — specialized/raw api only

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,10 +293,49 @@ 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.
 
+After a workspace URL slug changes, migrate its stored **API-key profile** with:
+
+```sh
+linear auth rename old-workspace new-workspace --json
+# Or include additional known project configs without editing them:
+linear auth rename old-workspace new-workspace --project-config /path/to/another/.linear.toml
+```
+
+The command validates the exact stored key against Linear's current organization/slug, preserving
+the credential, storage type, profile team, user workspace/default, and the reference CLI's shared
+keyring list/default. It ignores environment credentials and refuses credential flags. API-key
+profiles do not contain a historical organization ID; the unchanged key proves its own organization,
+which is returned in the result. Configured destinations and unlisted keyring entries are collisions,
+even if they contain the same key. Nothing is revoked, exported, or placed on argv.
+Keyring moves use an atomic create-only operation on macOS Keychain, so another client's
+destination created during the rename cannot be replaced. The Linux `secret-tool` backend lacks
+this operation and keyring-backed renames are refused before changes; file-only profiles remain
+supported when no source keyring entry needs moving.
+
+Project files are never edited. JSON reports `checkedProjectConfigs` and `projectConfigUpdates`
+with exact paths and old/new workspace values; human output lists the same required edits. Discovery
+covers the active project config plus explicit `--project-config` paths. Check other repositories
+separately, update their `workspace` selectors, and update `LINEAR_WORKSPACE` overrides. The reference
+CLI's global `linear.toml` selector, if affected, is reported in `globalConfigUpdates` for manual editing.
+
+If storage fails or the process stops partway through, repeat **the same rename command**. A
+non-secret `api_key_profile_rename` marker in the private user config reserves the destination and
+records recovery progress. The source is kept until a verified destination and committed metadata
+exist. Recovery checks for conflicting changes and resumes the remaining steps. Do not log out,
+replace, or migrate either profile while recovery is pending. Fix the reported store/permission
+problem, then retry; do not delete the recovery marker or print credential-store contents.
+
+OAuth user and app profiles (including dormant keyring records) are refused before validation or
+mutation. User sessions have rotating refresh tokens and require coordination with in-flight
+refreshes; app profiles contain organization-bound client credentials, and token exchanges with
+different scopes can revoke existing app tokens. This command does not refresh, exchange, revoke,
+or rename either OAuth lifecycle. It does not require browser authorization. See Linear's
+[OAuth lifecycle documentation](https://linear.app/developers/oauth-2-0-authentication).
+
 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.
@@ -484,6 +522,104 @@ linear cv results 01234567-89ab-cdef-0123-456789abcdef --json
 # [{"type":"issue","id":"…","identifier":"ENG-42","name":"Fix login","url":"…"}]
 ```
 
+### Releases
+
+`release`, `release-pipeline`, `release-stage`, and `release-note` provide native release tracking.
+Linear currently requires a [Business or Enterprise workspace](https://linear.app/docs/releases.md);
+Business supports up to 15 pipelines. Schema visibility or an empty list does not establish
+entitlement to create pipelines, or permission to change them. Linear enforces plan, role, team,
+and credential permissions; the CLI preserves `feature_not_accessible` and `forbidden` errors.
+
+These commands use the CLI's usual OAuth or personal API credentials and `--workspace` selection.
+Pipeline **access keys** are separate credentials for the official
+[`linear-release`](https://github.com/linear/linear-release) CI tool. Do not put a pipeline key in
+`LINEAR_API_KEY` or `LINEAR_ACCESS_TOKEN`. This CLI does not consume `LINEAR_ACCESS_KEY`, create
+pipeline keys, or invoke/install the official tool automatically.
+
+```sh
+linear release-pipeline list --json
+linear release-pipeline view production --json       # UUID or API slug; not display name
+linear release-stage list production --all --json
+linear release list --pipeline production --stage-type started --json
+linear release view RELEASE_ID --json                # release UUID or slug
+linear release issues RELEASE_ID --all --json
+linear release links RELEASE_ID --json
+```
+
+Create a pipeline explicitly as `scheduled` or `continuous`. Creation includes Linear's default
+stages. Add further `started` stages for verification/observation, or rename/reorder the defaults:
+
+```sh
+linear release-pipeline create --name Production --type scheduled --json
+linear release-pipeline update PIPELINE_ID --rollover-issues false --json
+linear release-stage create --pipeline PIPELINE_ID --name Observe --type started \
+  --color '#5e6ad2' --position 3 --frozen true --json
+linear release-stage update STAGE_ID --frozen false --json
+```
+
+Stage types are immutable. Only `started` stages can be frozen, and Linear requires at least one
+unfrozen started stage. Freezing excludes releases in that stage from automated sync; it is not a
+deployment approval or a lock on manual membership edits. Pipeline updates support explicit
+`true|false` for production, automatic notes, and issue rollover. Repeated `--include-path` and
+`--team-id` replace the corresponding collections; `--clear-paths` and `--clear-teams` clear them.
+Team associations use UUIDs, not the global default `--team`.
+
+For a scheduled rollout, create the release with a full commit SHA, explicit version and stage,
+then add the exact issue scope. `release create` otherwise defaults to a started stage on scheduled
+pipelines and a completed stage on continuous pipelines:
+
+```sh
+linear release create --pipeline PIPELINE_ID --name 'Release 1.2.3' \
+  --release-version 1.2.3 --commit-sha "$approved_sha" --stage PLANNED_STAGE_ID \
+  --target-date 2026-10-30 --description-file release-plan.md --json
+linear release add-issue RELEASE_ID ENG-42 --json
+linear release update RELEASE_ID --stage VERIFY_STAGE_ID --json
+linear release-note create --pipeline PIPELINE_ID --release RELEASE_ID \
+  --title 'Verification' --body-file verification.md --json
+```
+
+`release update <id>` edits that exact release, including SHA/version/dates or a stage UUID from
+the same pipeline. `release update-version`, `sync`, and `complete` require **both** `--pipeline`
+and `--release-version`; they never implicitly pick the latest release. `update-version` accepts a
+stage **name**, matched by Linear, and attaches links without changing the version:
+
+```sh
+linear release update-version --pipeline PIPELINE_ID --release-version 1.2.3 \
+  --stage Observe --link "CI=https://ci.example/run/123" --json
+# Only after the external deployment, verification and observation gates pass:
+linear release complete --pipeline PIPELINE_ID --release-version 1.2.3 \
+  --link "GitHub=https://github.com/acme/app/releases/tag/v1.2.3" --json
+```
+
+Completion records Linear lifecycle state; it does not deploy, enforce service ordering, check
+approvals, verify a running revision, or wait for observation. Completing a scheduled release may
+move its open issues into the next release (creating one if needed), depending on pipeline settings.
+When `complete --commit-sha` targets a version, Linear preserves an existing stored SHA. Set and
+verify the intended SHA with `create`/`update` first. Stage transitions through `update` also trigger
+Linear's lifecycle behavior, including rollover on completion.
+
+For explicit, already-attributed data, `release sync --pipeline PIPELINE_ID --release-version 1.2.3
+--commit-sha FULL_SHA --issue ENG-42 --issue ENG-43=OTHER_FULL_SHA` calls Linear's native sync API.
+It does not scan Git. References accumulate; omitted issues are not removed. `--reverted-issue`
+removes reverted attribution, and `release remove-issue RELEASE_ID ENG-42 --yes` removes exact
+membership. Scheduled sync can assign the version to an unversioned started release or create a
+release; continuous sync creates/completes a release immediately. Use sync at the appropriate point
+in your deployment process, and read the returned release ID, version, SHA and stage.
+
+Use the official `linear-release` when you need commit-range scanning, path/subject filters,
+revert detection, branch/PR attribution, and pipeline-key CI authentication. It can work alongside
+this CLI against the same pipeline; pass the same explicit release version. Native commands are
+useful for preparation, exact membership, management, inspection, and subsequent lifecycle steps.
+No Git attribution implementation or additional runtime dependency is duplicated here.
+
+Release notes can cover repeated `--release <id>` values, or an inclusive **createdAt** range using
+both `--from-release` and `--to-release`. These shapes are mutually exclusive and all releases must
+belong to the note's pipeline. `release-note update` changes title, Markdown or scope; delete needs
+confirmation (`--yes` noninteractively). Use `--body-file -` or `--description-file -` for stdin.
+List commands emit bare arrays, views and mutations emit objects, and errors remain JSON on stderr.
+`linear commands release sync --json` exposes options and output fields without credentials.
+Archive/trash operations and other advanced fields remain available through `linear api`.
+
 ## Command overview
 
 Every group has `--help` with full options and (for the busy ones) an Examples section. Aliases
@@ -498,6 +634,10 @@ are shown in parentheses. For a machine-readable tree of _every_ command, run
 | **`project-update`** (`pu`)    | `create` · `list` (project status updates, with `--health`)                                                                                                                                                                                                                                      |
 | **`milestone`** (`m`)          | `list` · `view` · `create` · `update` · `delete`                                                                                                                                                                                                                                                 |
 | **`cycle`** (`c`)              | `list` · `view` · `current` · `create` · `update`                                                                                                                                                                                                                                                |
+| **`release`**                  | `list` · `view` · `create` · `update` · `sync` · `update-version` · `complete` · `issues` · `links` · `add-issue` · `remove-issue`                                                                                                                                                               |
+| **`release-pipeline`**         | `list` · `view` · `create` · `update`                                                                                                                                                                                                                                                            |
+| **`release-stage`**            | `list` · `view` · `create` · `update`                                                                                                                                                                                                                                                            |
+| **`release-note`**             | `list` · `view` · `create` · `update` · `delete`                                                                                                                                                                                                                                                 |
 | **`user`** (`u`)               | `list` · `view` · `me`                                                                                                                                                                                                                                                                           |
 | **`label`** (`lb`)             | `list` · `create` · `update` · `delete`                                                                                                                                                                                                                                                          |
 | **`state`** (`st`)             | `list` · `view` (workflow states)                                                                                                                                                                                                                                                                |
@@ -556,6 +696,11 @@ resolver semantics are designed, rather than acquiring a silent partial implemen
 | `attachment list`                                      | `Issue.attachments`                           | yes            | not exposed                                    | not exposed                   |
 | `comment list`, `issue comment list`, `issue comments` | `Issue.comments`                              | yes            | not exposed                                    | not exposed                   |
 | `cycle list`, `team cycles`                            | `Team.cycles`                                 | yes            | not exposed                                    | not exposed                   |
+| `release list`                                         | `Query.releases`                              | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-pipeline list`                                | `Query.releasePipelines`                      | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-stage list`                                   | `ReleasePipeline.stages`                      | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-note list`                                    | `Query.releaseNotes`                          | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release issues`, `release links`                      | `Release.issues/links`                        | yes            | not exposed                                    | not exposed                   |
 | `custom-view list`                                     | `Query.customViews`                           | yes            | not exposed                                    | `archivedAt`                  |
 | `custom-view results`                                  | `CustomView.issues/projects/initiatives`      | yes            | not exposed                                    | not exposed                   |
 | `document list`                                        | `Query.documents`                             | yes            | not exposed                                    | not exposed                   |
@@ -772,10 +917,10 @@ profile slug where applicable:
    only, so a migrating user's defaults carry over
 7. no default team
 
-`workspace` and `sort` keep their existing flag → environment → project → user → legacy-global
+`workspace`, `project`, and `sort` use flag → environment → project → user → legacy-global
 order. Workspace credential selection is independent and follows the order described above.
 
-Keys: `team` (or `team_id`), `workspace`, and `sort` (or `issue_sort`). You can write these from
+Keys: `team` (or `team_id`), `workspace`, `project`, and `sort` (or `issue_sort`). You can write these from
 the CLI. Project and top-level setting edits preserve comments and layout. Profile updates preserve
 all TOML data and use the same locked, atomic rewrite as credential updates:
 
@@ -783,11 +928,26 @@ all TOML data and use the same locked, atomic rewrite as credential updates:
 linear config init                    # pick a team from a list → <git root>/.linear.toml
 linear config init --team TES         # …or say which (scripts); --sort, --path, --force
 linear config set sort updated        # edit one key in the project config in effect
+linear config set project "My Project" # default Linear project for new issues (name or UUID)
 linear config set team ENG --user     # legacy top-level user fallback (backward compatible)
 linear config set team ENG --user --workspace acme # validated default for the acme profile
 linear config                         # show the result, with each value's source
 ```
 
+To associate a particular folder and its descendants with a Linear project, run
+`linear config set project "My Project" --path .linear.toml` inside that folder. Without `--path`,
+`config set` edits the discovered config, or creates one at the Git root (cwd outside Git).
+Keep `team` and `workspace` in the same file when needed: discovery reads the nearest config
+file, without merging ancestor files.
+
+`issue create` (also `issue new`) uses this project automatically. `--project <name|id>` overrides
+it; sub-issues inherit their parent's project ahead of the configured default. `--no-project`
+creates outside any project, including parent and template defaults. `LINEAR_PROJECT` overrides
+the configured value for an invocation. A configured project is resolved before creation, so
+an unknown or ambiguous name fails without creating an issue; UUIDs avoid name ambiguity.
+This default applies to issue creation; list, search, and update commands keep their explicit
+project selection. Remove the `project` line from the config to clear the association.
+
 `config set` will not write `api_key` or anything else that belongs to the credential store — that
 is what `auth login` is for. A profile team is validated against the selected workspace whenever a
 credential is available. Login, adopt, OAuth refresh/fallback, and credential migration preserve

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",