linear-sdk-cli 0.8.3 → 0.9.0

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

@@ -0,0 +1,348 @@
+# linear release
+
+> Track releases and issue membership (Business/Enterprise)
+
+_Generated from `linear commands --json`. `linear release --help` (or `<subcommand> --help`) is authoritative._
+
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+
+### `linear release`
+
+Track releases and issue membership (Business/Enterprise)
+
+```
+linear release [options]
+```
+
+### `linear release add-issue`
+
+Add an issue (KEY-123 or UUID) to an exact release
+
+```
+linear release add-issue [options] <id> <issue>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+releaseId: string
+issueId: string
+identifier: string
+```
+
+### `linear release complete`
+
+Complete an explicit scheduled release; may roll open issues forward
+
+```
+linear release complete [options]
+```
+
+| Option                        | Description                                                          |
+| ----------------------------- | -------------------------------------------------------------------- |
+| `--description <text>`        | release description (Markdown)                                       |
+| `--description-file <path>`   | read description from file ('-' for stdin)                           |
+| `--clear-description`         | clear the description                                                |
+| `--pipeline <id\|slug>`       | target pipeline UUID or slug                                         |
+| `--release-version <version>` | explicit release version within the pipeline (no latest fallback)    |
+| `--name <name>`               | release name                                                         |
+| `--link <label=url\|url>`     | attach an external link (repeatable)                                 |
+| `--commit-sha <sha>`          | full SHA (Linear preserves an existing SHA when targeting a version) |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```
+
+### `linear release create`
+
+Create a release (stage defaults depend on pipeline type)
+
+Aliases: `new`
+
+```
+linear release create [options]
+```
+
+| Option                        | Description                                  |
+| ----------------------------- | -------------------------------------------- |
+| `--description <text>`        | release description (Markdown)               |
+| `--description-file <path>`   | read description from file ('-' for stdin)   |
+| `--clear-description`         | clear the description                        |
+| `--name <name>`               | release name                                 |
+| `--release-version <version>` | release version (unique within the pipeline) |
+| `--commit-sha <sha>`          | full Git commit SHA                          |
+| `--stage <id>`                | stage UUID from the same pipeline            |
+| `--start-date <date>`         | estimated start date (YYYY-MM-DD)            |
+| `--target-date <date>`        | estimated completion date (YYYY-MM-DD)       |
+| `--pipeline <id\|slug>`       | pipeline UUID or slug                        |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```
+
+### `linear release issues`
+
+List issues in a release (UUID or slug)
+
+```
+linear release issues [options] <id>
+```
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+identifier: string
+title: string
+url: string
+```
+
+### `linear release links`
+
+List external links on a release (UUID or slug)
+
+```
+linear release links [options] <id>
+```
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+label: string | null
+url: string
+```
+
+### `linear release list`
+
+List releases, optionally scoped to a pipeline
+
+Aliases: `ls`
+
+```
+linear release list [options]
+```
+
+| Option                        | Description                     |
+| ----------------------------- | ------------------------------- |
+| `--pipeline <id\|slug>`       | filter by pipeline UUID or slug |
+| `--release-version <version>` | filter by exact version         |
+| `--stage-type <type>`         | filter by lifecycle stage type  |
+| `--include-archived`          | include archived releases       |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+```
+
+### `linear release remove-issue`
+
+Remove an issue from an exact release
+
+```
+linear release remove-issue [options] <id> <issue>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+releaseId: string
+issue: string
+removed: boolean
+```
+
+### `linear release sync`
+
+Sync explicit issue references; continuous pipelines complete immediately
+
+```
+linear release sync [options]
+```
+
+| Option                         | Description                                                       |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `--description <text>`         | release description (Markdown)                                    |
+| `--description-file <path>`    | read description from file ('-' for stdin)                        |
+| `--clear-description`          | clear the description                                             |
+| `--pipeline <id\|slug>`        | target pipeline UUID or slug                                      |
+| `--release-version <version>`  | explicit release version within the pipeline (no latest fallback) |
+| `--name <name>`                | release name                                                      |
+| `--link <label=url\|url>`      | attach an external link (repeatable)                              |
+| `--commit-sha <sha>`           | full Git commit SHA (no implicit checkout scanning)               |
+| `--issue <key[=sha]>`          | issue reference, defaulting to --commit-sha (repeatable)          |
+| `--reverted-issue <key[=sha]>` | reverted issue reference to remove (repeatable)                   |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```
+
+### `linear release update`
+
+Update exact release metadata or stage by UUID/slug
+
+Aliases: `edit`
+
+```
+linear release update [options] <id>
+```
+
+| Option                        | Description                                  |
+| ----------------------------- | -------------------------------------------- |
+| `--description <text>`        | release description (Markdown)               |
+| `--description-file <path>`   | read description from file ('-' for stdin)   |
+| `--clear-description`         | clear the description                        |
+| `--name <name>`               | release name                                 |
+| `--release-version <version>` | release version (unique within the pipeline) |
+| `--commit-sha <sha>`          | full Git commit SHA                          |
+| `--stage <id>`                | stage UUID from the same pipeline            |
+| `--start-date <date>`         | estimated start date (YYYY-MM-DD)            |
+| `--target-date <date>`        | estimated completion date (YYYY-MM-DD)       |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```
+
+### `linear release update-version`
+
+Update stage/name/links for an explicit pipeline and release version
+
+```
+linear release update-version [options]
+```
+
+| Option                        | Description                                                       |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `--description <text>`        | release description (Markdown)                                    |
+| `--description-file <path>`   | read description from file ('-' for stdin)                        |
+| `--clear-description`         | clear the description                                             |
+| `--pipeline <id\|slug>`       | target pipeline UUID or slug                                      |
+| `--release-version <version>` | explicit release version within the pipeline (no latest fallback) |
+| `--name <name>`               | release name                                                      |
+| `--link <label=url\|url>`     | attach an external link (repeatable)                              |
+| `--stage <name>`              | stage name (Linear matches exact name, then normalized name)      |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```
+
+### `linear release view`
+
+Show a release by UUID or slug
+
+```
+linear release view [options] <id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+name: string
+version: string | null
+commitSha: string | null
+url: string
+pipeline: {id: string, name: string, type: string}
+stage: {id: string, name: string, type: string, frozen: boolean}
+startDate: string | null
+targetDate: string | null
+startedAt: string | null
+completedAt: string | null
+canceledAt: string | null
+archivedAt: string | null
+description: string | null
+issueCount: number
+```

package/src/cli.ts

@@ -19,6 +19,10 @@ import { registerProjectLabel } from "./commands/project-label.js";
 import { registerProjectUpdate } from "./commands/project-update.js";
 import { registerMilestone } from "./commands/milestone.js";
 import { registerCycle } from "./commands/cycle.js";
+import { registerRelease } from "./commands/release.js";
+import { registerReleasePipeline } from "./commands/release-pipeline.js";
+import { registerReleaseStage } from "./commands/release-stage.js";
+import { registerReleaseNote } from "./commands/release-note.js";
 import { registerUser } from "./commands/user.js";
 import { registerLabel } from "./commands/label.js";
 import { registerState } from "./commands/state.js";
@@ -94,6 +98,10 @@ export function createProgram(): Command {
   registerProjectUpdate(program);
   registerMilestone(program);
   registerCycle(program);
+  registerRelease(program);
+  registerReleasePipeline(program);
+  registerReleaseStage(program);
+  registerReleaseNote(program);
   // Phase 3: users, labels, workflow states, comments, documents, attachments, favorites.
   registerUser(program);
   registerLabel(program);

package/src/commands/issue.ts

@@ -371,8 +371,12 @@ export function registerIssue(program: Command): void {
     .option("-s, --state <name>", "workflow state name or type")
     .option("-P, --priority <0-4>", "priority", parsePriority)
     .option("-l, --label <name>", "label (repeatable / comma-separated)", parseList)
-    .option("-p, --project <name>", "project name or id")
-    .option("--milestone <name>", "project milestone (requires --project)")
+    .option("-p, --project <name>", "project name or id (overrides the configured default)")
+    .option("--no-project", "create outside any project, ignoring configured and parent defaults")
+    .option(
+      "--milestone <name>",
+      "project milestone (requires an explicit, configured, or parent project)",
+    )
     .option(CYCLE_FLAG, CYCLE_DESC)
     .option("--estimate <n>", "estimate points", parseIntOption)
     .option(
@@ -391,6 +395,7 @@ export function registerIssue(program: Command): void {
       [
         "",
         "Examples:",
+        "  linear config set project 'My Project'                      # default for this folder/repo",
         "  linear issue create --title 'Fix login' --team TES --assignee me",
         "  linear issue create --title 'Fix login' --assignee me --delegate Codex",
         "  linear issue create --title 'Fix login' --delegate Codex --dry-run --json",
@@ -438,7 +443,8 @@ export function registerIssue(program: Command): void {
             state: opts.state,
             priority: opts.priority,
             label: opts.label,
-            project: opts.project,
+            project: opts.project === false ? null : opts.project,
+            defaultProject: ctx.config.project,
             milestone: opts.milestone,
             cycle: opts.cycle,
             estimate: opts.estimate,

package/src/commands/meta.ts

@@ -1,6 +1,6 @@
 /**
  * Top-level meta commands: whoami, auth (login/list/default/token/status/
- * logout/migrate), config.
+ * logout/rename/migrate), config.
  */
 
 import { Command } from "commander";
@@ -20,6 +20,8 @@ import {
   readOAuthCredential,
   writeOAuthCredential,
   migrateCredentials,
+  renameApiKeyProfile,
+  profileRenameProjectUpdates,
   redactKey,
   resolveConfig,
   defaultProjectConfigPath,
@@ -631,6 +633,80 @@ export function registerMeta(program: Command): void {
       }),
     );
 
+  // rename ------------------------------------------------------------------
+  auth
+    .command("rename <old-slug> <new-slug>")
+    .description("Rename a stored API-key profile after its Linear workspace URL slug changes")
+    .option(
+      "--project-config <paths...>",
+      "also inspect these project configs for old workspace selectors (read-only)",
+    )
+    .addHelpText(
+      "after",
+      `
+Validates the exact stored API key against the current Linear workspace slug.
+Preserves the key, profile team, user workspace/default, and shared keyring list.
+Refuses configured or unlisted keyring destinations; never overwrites or revokes.
+Keyring moves require atomic create-only support (macOS Keychain). Linux Secret
+Service entries are refused; file-only API-key profiles are supported.
+An interrupted rename can be resumed by repeating the same command.
+OAuth user/app profiles are not supported; their credentials and grants stay unchanged.
+Project files are never edited. Reports the discovered project config and any
+--project-config paths needing updates; other repositories must be checked separately.
+Example: linear auth rename old-workspace new-workspace --json`,
+    )
+    .action(
+      action(async (ctx: Context, opts, oldSlug: string, newSlug: string) => {
+        const from = explicitWorkspaceSlug(oldSlug);
+        const to = explicitWorkspaceSlug(newSlug);
+        if (ctx.options.workspace && ctx.options.workspace !== from)
+          throw usageError("--workspace must match <old-slug> when renaming a profile.");
+        if (ctx.options.apiKey || ctx.options.accessToken)
+          throw usageError(
+            "`auth rename` uses only the named stored profile; remove credential flags.",
+          );
+        const checkedProjectConfigs = [
+          ...new Set([
+            ...(ctx.config.projectConfigPath ? [ctx.config.projectConfigPath] : []),
+            ...(opts.projectConfig ?? []).map((path: string) => resolve(path)),
+          ]),
+        ] as string[];
+        const projectConfigUpdates = profileRenameProjectUpdates(from, to, checkedProjectConfigs);
+        const globalConfigUpdates = profileRenameProjectUpdates(
+          from,
+          to,
+          ctx.config.globalConfigPath ? [ctx.config.globalConfigPath] : [],
+        );
+        let organization: AuthIdentity["organization"] | undefined;
+        const saved = await renameApiKeyProfile(from, to, async (key) => {
+          organization = (await validateAuthCredential(key, to)).organization;
+        });
+        const otherProjects = `Update workspace = "${from}" to "${to}" in other project configs and LINEAR_WORKSPACE overrides. Only the listed project paths were checked.`;
+        ctx.output.emit(
+          {
+            success: true,
+            from,
+            workspace: to,
+            credentialType: "api-key",
+            organization: organization!,
+            ...saved,
+            checkedProjectConfigs,
+            projectConfigUpdates,
+            globalConfigUpdates,
+            otherProjects,
+          },
+          () => {
+            ctx.output.success(
+              `Renamed API-key profile '${from}' to '${to}'. Credential preserved; no grant revoked.`,
+            );
+            for (const update of [...projectConfigUpdates, ...globalConfigUpdates])
+              ctx.output.info(`Update ${update.path}: workspace = "${to}" (currently "${from}").`);
+            ctx.output.info(otherProjects);
+          },
+        );
+      }),
+    );
+
   // migrate -----------------------------------------------------------------
   auth
     .command("migrate")
@@ -753,6 +829,7 @@ export function registerMeta(program: Command): void {
             workspaceProfile: c.workspaceProfile ?? null,
             team: c.team ?? null,
             workspace: c.workspace ?? null,
+            project: c.project ?? null,
             sort: c.sort,
             origins: c.origins,
             userConfigPath: c.userConfigPath,
@@ -766,6 +843,7 @@ export function registerMeta(program: Command): void {
             ["Workspace profile", c.workspaceProfile ?? "(none)"],
             ["Team", show("team", c.team)],
             ["Workspace", show("workspace", c.workspace)],
+            ["Default issue project", show("project", c.project)],
             ["Sort", show("sort", c.sort)],
             ["User config", c.userConfigPath],
             ["Project config", c.projectConfigPath],
@@ -780,6 +858,7 @@ export function registerMeta(program: Command): void {
     .command("init")
     .description("Write a project .linear.toml (at the git root, or here outside a repository)")
     .option("--team <key>", "default team key (otherwise chosen from a list)")
+    .option("--project <name|id>", "default Linear project for new issues")
     .option("--sort <order>", `default issue-list sort (${ISSUE_SORTS.join(" | ")})`)
     .option("--path <file>", "write this file instead of <git root>/.linear.toml")
     .option("--force", "overwrite an existing file")
@@ -808,10 +887,11 @@ export function registerMeta(program: Command): void {
           team: validateSetting("team", team),
         };
         if (opts.sort !== undefined) settings.sort = validateSetting("sort", opts.sort);
+        if (opts.project !== undefined) settings.project = validateSetting("project", opts.project);
         initProjectConfig(path, settings, { force: opts.force === true });
         ctx.output.emit({ success: true, path, ...settings }, () =>
           ctx.output.success(
-            `Wrote ${path} (team ${settings.team}${settings.sort ? `, sort ${settings.sort}` : ""}).`,
+            `Wrote ${path} (team ${settings.team}${settings.project ? `, project ${settings.project}` : ""}${settings.sort ? `, sort ${settings.sort}` : ""}).`,
           ),
         );
       }),

package/src/commands/release-note.ts

@@ -0,0 +1,90 @@
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { noteOptions, noteInput } from "../lib/release-input.js";
+import { confirmDestructive } from "../lib/prompt.js";
+import * as svc from "../services/release.js";
+
+export function registerReleaseNote(program: Command): void {
+  const group = program
+    .command("release-note")
+    .description("Manage Markdown notes covering one or more releases");
+  group
+    .command("list")
+    .alias("ls")
+    .description("List release notes with optional pipeline/release filters")
+    .option("--pipeline <id|slug>", "filter by pipeline UUID or slug")
+    .option("--release <id>", "filter by covered release UUID or slug")
+    .option("--include-archived", "include archived notes")
+    .action(
+      action(async (ctx, opts) => {
+        const rows = await svc.listNotes(ctx.client, ctx.limit, opts);
+        ctx.output.list(
+          rows,
+          [
+            { key: "id", header: "ID", value: (r) => r.id },
+            { key: "title", header: "Title", value: (r) => r.title ?? "—" },
+            { key: "pipeline", header: "Pipeline", value: (r) => r.pipeline.name },
+            { key: "releaseCount", header: "Releases", value: (r) => r.releaseCount },
+          ],
+          rows,
+        );
+      }),
+    );
+  group
+    .command("view <id>")
+    .description("Show a release note and its Markdown body by UUID or slug")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const n = await svc.getNote(ctx.client, id);
+        ctx.output.detail(n, [
+          ["ID", n.id],
+          ["Title", n.title],
+          ["Pipeline", n.pipeline.name],
+          ["Releases", n.releaseCount],
+          ["First release", n.firstRelease?.name],
+          ["Last release", n.lastRelease?.name],
+          ["Generation status", n.generationStatus],
+          ["Archived", n.archivedAt],
+          ["URL", n.url],
+          ["Content", n.content],
+        ]);
+      }),
+    );
+  noteOptions(
+    group
+      .command("create")
+      .description("Create a note for explicit releases or an inclusive createdAt range"),
+  )
+    .requiredOption("--pipeline <id|slug>", "pipeline UUID or slug")
+    .action(
+      action(async (ctx, opts) => {
+        const input = noteInput(opts);
+        svc.validateNoteScope(input, true);
+        const n = await svc.createNote(ctx.client, opts.pipeline, input);
+        ctx.output.emit(n, () => ctx.output.success(`Created release note ${n.id}`));
+      }),
+    );
+  noteOptions(
+    group
+      .command("update <id>")
+      .description("Update a note's title, Markdown, or covered releases"),
+  ).action(
+    action(async (ctx, opts, id: string) => {
+      const input = noteInput(opts);
+      svc.validateNoteScope(input, false);
+      const n = await svc.updateNote(ctx.client, id, input);
+      ctx.output.emit(n, () => ctx.output.success(`Updated release note ${n.id}`));
+    }),
+  );
+  group
+    .command("delete <id>")
+    .description("Delete a release note by UUID or slug")
+    .action(
+      action(async (ctx, _opts, id: string) => {
+        const n = await svc.getNote(ctx.client, id);
+        if (!(await confirmDestructive(ctx, `Delete release note ${n.title ?? n.id}?`))) return;
+        const receipt = await svc.deleteNote(ctx.client, n.id);
+        ctx.output.emit(receipt, () => ctx.output.success(`Deleted release note ${receipt.id}`));
+      }),
+    );
+}