linear-sdk-cli 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.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
+
+- **deps:** finish SDK and formatter upgrades ([b511b91](https://github.com/zhendalf/linear-sdk-cli/commit/b511b91d37fee6c85e362ff1eb436985176fc5cc))
+- **deps:** update compatible dependency versions ([0f89628](https://github.com/zhendalf/linear-sdk-cli/commit/0f89628c9f2dd4aa63f02a7b4139822e8cea3540))
+
 ## [0.8.2](https://github.com/zhendalf/linear-sdk-cli/compare/v0.8.1...v0.8.2) (2026-10-13)
 
 ### Bug Fixes
@@ -187,7 +201,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `completion`), `fields` (key → `"string"`, `"number|null"`, `["string"]`, nested `{…}`,
   `{nullable: {…}}` for a relation that may be null, `"comments?"` for a key present only
   sometimes) and `variants` (the whole shape under `--web`, `--start`, `op=list`, …). New `linear
-commands <path...>` describes one command — a bare object under `--json` (`.output.fields`),
+  commands <path...>` describes one command — a bare object under `--json` (`.output.fields`),
   or usage, options and one `key: type` line per field for a human, plus its subcommands for a
   group; an unknown path is `not_found` (exit 3) with the nearest paths. The shapes are declared
   beside the interfaces they describe (`shape<IssueRow>({…})`, `src/lib/shape.ts`), where a field
@@ -232,9 +246,9 @@ commands <path...>` describes one command — a bare object under `--json` (`.ou
   TES-642).** `initiative add-project <initiative> <project>` (`--sort-order`) and
   `remove-project` (confirmed; finds the link on the project's side, so no workspace-wide paging)
   and `initiative unarchive <id>` (resolves among archived initiatives, refuses a live one). `initiative
-list` gains `--status`, `--owner`, `--archived` — the list stays every-status by default, and
+  list` gains `--status`, `--owner`, `--archived` — the list stays every-status by default, and
   the reference CLI's `--all-statuses` is accepted as the no-op it is here. `initiative
-create/update` take `--icon`/`--color`, and `initiative view` shows `icon`, `archivedAt` and
+  create/update` take `--icon`/`--color`, and `initiative view` shows `icon`, `archivedAt` and
   the linked `projects` (`{id, name, status}`).
 - **`project list --all-teams`, `team create --private`, health-only status updates (TES-642).**
   `project list` is scoped to the default team and the only way out was the accidental
@@ -439,7 +453,7 @@ create/update` take `--icon`/`--color`, and `initiative view` shows `icon`, `arc
   fills. **The team's default template is now applied**, as Linear's own new-issue form and the
   reference CLI do: the API applies it _only when asked_ (verified live — a plain `issueCreate` on
   a team with a default template returns an issue with no description), so `useDefaultTemplate:
-true` is sent unless `--no-default-template` (also accepted under the reference's spelling,
+  true` is sent unless `--no-default-template` (also accepted under the reference's spelling,
   `--no-use-default-template`); an explicit `--template` replaces it rather than stacking. A
   `--parent` child now **joins its parent's project** unless `--project` says otherwise — the
   sub-issues we created landed outside the project their parent was in — and `--milestone` can
@@ -455,7 +469,7 @@ true` is sent unless `--no-default-template` (also accepted under the reference'
   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`
   cap or exhaust a _paged_ query; on the ~90 commands that print a receipt (every mutation, `issue
-id`, `commands`, …) all three used to vanish without a word. That silence cost data: schpet's `-f`
+  id`, `commands`, …) all three used to vanish without a word. That silence cost data: schpet's `-f`
   is `--description-file` on `project create`, so `linear project create --name X -f desc.md`
   parsed `-f` as _our_ `--fields`, created the project with **no description**, and exited 0. Now a
   root `preAction` hook (`assertGlobalsApply` in `lib/options.ts`, driven by two applicability
@@ -492,7 +506,7 @@ id`, `commands`, …) all three used to vanish without a word. That silence cost
   the PR `ID Title` and stops copying the issue description into GitHub** (TES-637 (5)).
   `describe` used to print `Title`, a blank line, `Fixes ID`; it now prints `ID Title`, a blank
   line, `Linear-issue: Fixes ID`, `Linear-issue-url: <url>` — git trailers that `git
-interpret-trailers` / `git log --format=%(trailers:key=Linear-issue)` and jj's `trailers`
+  interpret-trailers` / `git log --format=%(trailers:key=Linear-issue)` and jj's `trailers`
   template read back, while Linear still sees the magic word directly before the id
   (linear.app/docs/github lists `fixes` and `references` among the recognized words) and links
   and closes the issue. `-r/--references` swaps the word. `--json` gains `url` and `message` (the
@@ -502,7 +516,7 @@ interpret-trailers` / `git log --format=%(trailers:key=Linear-issue)` and jj's `
   renamed. The issue _description_ is no longer pasted into the PR body: a GitHub PR is a wider
   audience than a Linear issue, and Linear links from the trailer, not the prose.
 - **A team-scoped listing with no team says it is listing every team's** (TES-637 (8)). `issue
-list`/`mine`/`search` and `project list` with no `--team`, no configured team and no
+  list`/`mine`/`search` and `project list` with no `--team`, no configured team and no
   `--all-teams` list the whole workspace — by design; schpet errors there ("No default team…"), so
   someone arriving from it could read the workspace as the team. One `info` line on stderr ("No
   default team configured; listing every team's. Pass --team <KEY> …"), silenced by `--quiet`,
@@ -605,7 +619,7 @@ list`/`mine`/`search` and `project list` with no `--team`, no configured team an
 
 - **`issue list`/`mine`/`search` rows omitted `milestone` and `cycle`** (TES-652). The list
   query selected project and labels but neither relation, so `issue list --project X --json | jq
-'group_by(.milestone.name)'` put every issue in the null bucket while `issue view` showed the
+  'group_by(.milestone.name)'` put every issue in the null bucket while `issue view` showed the
   milestone. Rows now carry `milestone: {id, name} | null` and `cycle: {id, number, name} | null`
   — the detail's exact object shapes, from the one existing query (two selections, no extra
   request; `LIST_QUERY` and `SEARCH_QUERY` share the relation block so they cannot drift again).
@@ -626,7 +640,7 @@ list`/`mine`/`search` and `project list` with no `--team`, no configured team an
   Non-interactively, `comment update <id>` with no body is a usage error, not an editor.
 - **`issue comment "<body>"` on a matching branch failed** (TES-619) — the README's headline
   example. `issue comment [id] [body]` read a lone operand as the id, so `linear issue comment
-'shipped'` on `tes-615-…` produced "No comment body provided" (and, in a terminal, opened
+  'shipped'` on `tes-615-…` produced "No comment body provided" (and, in a terminal, opened
   `$EDITOR` for the body first and only then rejected `'shipped'` as an id — work lost).
   `assign` and `state` already disambiguated a lone operand; `comment` now does the same: one
   operand that looks like an issue id is the id (body from `--body-file` or the editor), anything
@@ -656,7 +670,7 @@ list`/`mine`/`search` and `project list` with no `--team`, no configured team an
   `--help`; a bare group shows its help** (TES-633). The root has an action (bare `linear` shows the
   branch's issue) and `issue` has a default subcommand (`view`), so commander's own "unknown
   command" never fired for either: `linear issues list` was `too many arguments. Expected 0
-arguments but got 2: issues, list.` and `linear issue lst` was `'lst' is not a valid issue id`.
+  arguments but got 2: issues, list.` and `linear issue lst` was `'lst' is not a valid issue id`.
   Now: `Unknown command 'issues'. Did you mean 'issue'? Run 'linear --help' to see the commands.`
   and `'lst' is not a valid issue id (…). Did you mean 'linear issue list'?` — a prefix (`proj`),
   a small typo (`lable`, `isue`) or an alias (`docs`, `notif`) is close enough; two-letter aliases
@@ -691,7 +705,7 @@ arguments but got 2: issues, list.` and `linear issue lst` was `'lst' is not a v
   resolves the name inside that project (names are unique per project only, the same rule
   `issue update --milestone` applies); a name without `--project` is a usage error that says so:
   `'…' is not a milestone id; pass --project <name|id> to look a milestone up by name.` `state view
-<name-or-type>` resolves against `--team` or the configured default team, exactly as
+  <name-or-type>` resolves against `--team` or the configured default team, exactly as
   `issue create --state` does, and says to pass `--team` when there is neither. UUIDs still go
   straight through.
 - **`milestone list`/`view` printed progress ×100 — `3846%`** (TES-648, found while fixing the
@@ -814,7 +828,7 @@ arguments but got 2: issues, list.` and `linear issue lst` was `'lst' is not a v
   issue id inferred from the current branch as usual. `issue describe [id]` prints the issue
   title plus a commit-message trailer using Linear's git magic words (`Fixes <ID>`, or
   `References <ID>` with `-r`/`--references`) — drop it into `git commit -m "$(linear issue
-describe)"`. `issue pull-request [id]` (alias `pr`) creates a GitHub PR via the `gh` CLI:
+  describe)"`. `issue pull-request [id]` (alias `pr`) creates a GitHub PR via the `gh` CLI:
   the title defaults to the issue title (`--title` to override) and the body is the issue
   description followed by a `Fixes <ID>` trailer and the Linear URL, so the PR and issue
   reference each other. Flags: `--base`, `--head`, `--draft`, `--web`. The created PR URL is the
@@ -823,8 +837,8 @@ describe)"`. `issue pull-request [id]` (alias `pr`) creates a GitHub PR via the
   or when `gh` itself fails.
 - **Multi-workspace credentials.** Store API keys for several workspaces and switch between
   them. New `auth` subcommands: `auth list` (configured workspaces + default), `auth default
-<slug>` (set the default), and `auth token` (print the resolved key for scripting). `auth
-login` now accepts the global `--workspace <slug>` (derived from the key's organization when
+  <slug>` (set the default), and `auth token` (print the resolved key for scripting). `auth
+  login` now accepts the global `--workspace <slug>` (derived from the key's organization when
   omitted) and `auth status` reports the active credential workspace. A new global
   `--workspace <slug>` selects which stored credential to use for any command. Credentials live
   in quoted `[workspaces."<slug>"]` tables under a top-level `default_workspace`. Credential
@@ -928,7 +942,7 @@ login` now accepts the global `--workspace <slug>` (derived from the key's organ
   stderr, where it lands in scrollback, CI logs and bug reports. The same channel let a project
   `.linear.toml` — a file that is not ours and may arrive with a checkout — emit raw escape
   sequences through our error output. We now report only the reason and the position (`line 3,
-column 36`), never an excerpt from a credential-bearing file, and strip control characters and
+  column 36`), never an excerpt from a credential-bearing file, and strip control characters and
   bidi overrides from what remains. The error stays actionable: it still says exactly where to look.
 - **Credential writes could lose a config or leave a truncated one.** Writing the config in place
   truncates it first, so a crash or a concurrently-running `linear` could observe — or leave behind

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

@@ -179,7 +179,7 @@ Every one is now either identical, or says so on stderr, or is a usage error. Kn
 8. **`issue describe`** — theirs prints `ID Title`, a blank line, then `Linear-issue: Fixes ID` and
    `Linear-issue-url: URL`; ours printed `Title` and a bare `Fixes ID`. Piped into `git commit -m`
    that was a different commit. Adopted, byte for byte: proper trailers are what `git
-interpret-trailers` and jj read back, and Linear reads the magic word right before the id
+   interpret-trailers` and jj read back, and Linear reads the magic word right before the id
    either way (linear.app/docs/github). `-r/--references` still swaps in `References`.
 9. **`issue pull-request`** — theirs titles the PR `ID Title` and sends the issue URL as the body;
    ours titled it `Title` and pasted the issue _description_ into the body. Title adopted (a custom

package/README.md

@@ -298,6 +298,45 @@ Successful browser, app, and API-key login also save `workspace = "<authenticate
 
 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 +523,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 +635,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 +697,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 +918,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 +929,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
@@ -795,15 +956,15 @@ profile metadata. Logout reports whether removing a whole profile also removed i
 
 ```toml
 # ~/.config/linear/config.toml
-default_workspace = "acme"     # which stored credential is active
-team = "TES"                   # optional legacy/global fallback team
-sort = "priority"              # default issue-list sort: priority | updated | created
+default_workspace = "acme" # which stored credential is active
+team = "TES" # optional legacy/global fallback team
+sort = "priority" # default issue-list sort: priority | updated | created
 
-[workspaces."acme"]            # per-workspace credentials (hyphenated slugs are quoted)
-keyring = true                 # secret lives in the OS keyring (service linear-cli, account acme)
-team = "ENG"                   # non-secret default team for this workspace
+[workspaces."acme"] # per-workspace credentials (hyphenated slugs are quoted)
+keyring = true # secret lives in the OS keyring (service linear-cli, account acme)
+team = "ENG" # non-secret default team for this workspace
 [workspaces."other-org"]
-api_key = "lin_api_yyyyyyyy"   # …or, with `auth login --plaintext`, in this 0600 file
+api_key = "lin_api_yyyyyyyy" # …or, with `auth login --plaintext`, in this 0600 file
 team = "OPS"
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",
@@ -54,8 +54,8 @@
     "lin": "bun run src/bin/linear.ts",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
-    "format": "oxfmt .",
-    "format:check": "oxfmt --check .",
+    "format": "oxfmt . '!CHANGELOG.md'",
+    "format:check": "oxfmt --check . '!CHANGELOG.md'",
     "test": "bun test test/unit test/contract",
     "test:performance": "bun test --timeout 15000 test/performance",
     "test:unit": "bun test test/unit",
@@ -71,7 +71,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.3",
-    "@linear/sdk": "^97.1.0",
+    "@linear/sdk": "^98.0.0",
     "commander": "^15.0.0",
     "graphql": "^17.0.2",
     "picocolors": "^1.1.1",
@@ -81,8 +81,8 @@
   "devDependencies": {
     "@types/bun": "^1.4.3",
     "@types/node": "^26.6.5",
-    "oxfmt": "^0.71.0",
-    "oxlint": "^1.87.0",
+    "oxfmt": "^0.73.0",
+    "oxlint": "^1.88.0",
     "typescript": "^7.0.2"
   }
 }