@enrichlayer/el-linear 1.6.0 → 1.7.0

package/README.md

@@ -74,13 +74,41 @@ every team ends up writing themselves:
 
 ## Authentication
 
-The API token is resolved in this order:
+el-linear supports either OAuth or a personal Linear API token. OAuth is
+configured with:
+
+```bash
+el-linear init oauth
+```
+
+By default, that command walks you through registering your own Linear OAuth
+app. Teams can make the flow a single browser authorization step by writing a
+local, untracked app-defaults file at `~/.config/el-linear/team-oauth.json`
+or pointing `EL_LINEAR_OAUTH_CONFIG` at one:
+
+```json
+{
+  "linearOAuth": {
+    "clientId": "your-linear-oauth-client-id",
+    "redirectPort": 8765,
+    "scopes": ["read", "write", "issues:create", "comments:create"],
+    "passwordManagerPath": "op://vault/item/client_id"
+  }
+}
+```
+
+`passwordManagerPath` is optional metadata for humans/scripts; el-linear does
+not execute password-manager commands from it. Do not put a `client_secret` in
+this shared file. The OAuth flow uses PKCE.
+
+At runtime, credentials are resolved in this order:
 
 1. `--api-token <token>` flag.
 2. `LINEAR_API_TOKEN` environment variable.
-3. **Active profile's** `~/.config/el-linear/profiles/<name>/token` file (see *Profiles* below).
-4. `~/.config/el-linear/token` file (legacy single-profile, recommended for human use when only one workspace is needed).
-5. `~/.linear_api_token` file (legacy, still honored).
+3. **Active profile's** OAuth state (`oauth.json`) from `el-linear init oauth`.
+4. **Active profile's** `~/.config/el-linear/profiles/<name>/token` file (see *Profiles* below).
+5. `~/.config/el-linear/token` file (legacy single-profile, recommended for human use when only one workspace is needed).
+6. `~/.linear_api_token` file (legacy, still honored).
 
 el-linear never logs the token.
 

package/dist/auth/oauth-app-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Optional local OAuth app defaults.
+ *
+ * This deliberately lives outside the packaged/default config. Teams can
+ * materialize it from a password manager, while the OSS CLI keeps requiring
+ * users to bring their own OAuth app when no local file exists.
+ */
+import { type OAuthScope } from "./oauth-client.js";
+export declare const TEAM_OAUTH_CONFIG_ENV = "EL_LINEAR_OAUTH_CONFIG";
+export interface TeamOAuthConfig {
+    clientId: string;
+    redirectPort: number;
+    scopes: OAuthScope[];
+    /**
+     * Optional human-facing pointer such as `op://vault/item/client_id`.
+     * The CLI does not execute password-manager commands from this value.
+     */
+    passwordManagerPath?: string;
+    sourcePath: string;
+}
+export declare function readTeamOAuthConfig(env?: NodeJS.ProcessEnv): Promise<TeamOAuthConfig | null>;

package/dist/auth/oauth-app-config.js

@@ -0,0 +1,82 @@
+/**
+ * Optional local OAuth app defaults.
+ *
+ * This deliberately lives outside the packaged/default config. Teams can
+ * materialize it from a password manager, while the OSS CLI keeps requiring
+ * users to bring their own OAuth app when no local file exists.
+ */
+import fs from "node:fs/promises";
+import { TEAM_OAUTH_CONFIG_PATH } from "../config/paths.js";
+import { DEFAULT_SCOPES, validateScopes, } from "./oauth-client.js";
+export const TEAM_OAUTH_CONFIG_ENV = "EL_LINEAR_OAUTH_CONFIG";
+export async function readTeamOAuthConfig(env = process.env) {
+    const envPath = env[TEAM_OAUTH_CONFIG_ENV]?.trim();
+    const sourcePath = envPath || TEAM_OAUTH_CONFIG_PATH;
+    let raw;
+    try {
+        raw = await fs.readFile(sourcePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT" && !envPath) {
+            return null;
+        }
+        if (err.code === "ENOENT") {
+            throw new Error(`${TEAM_OAUTH_CONFIG_ENV} points to ${sourcePath}, but that file does not exist.`);
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse ${sourcePath}: ${message}`);
+    }
+    const linearOAuth = parsed.linearOAuth;
+    if (!linearOAuth || typeof linearOAuth !== "object") {
+        throw new Error(`${sourcePath} must contain a linearOAuth object with a clientId.`);
+    }
+    const clientId = typeof linearOAuth.clientId === "string" ? linearOAuth.clientId.trim() : "";
+    if (!clientId) {
+        throw new Error(`${sourcePath} linearOAuth.clientId must be a string.`);
+    }
+    const redirectPort = parseRedirectPort(linearOAuth.redirectPort, sourcePath);
+    const scopes = parseScopes(linearOAuth.scopes, sourcePath);
+    const passwordManagerPath = parsePasswordManagerPath(linearOAuth.passwordManagerPath, sourcePath);
+    return {
+        clientId,
+        redirectPort,
+        scopes,
+        passwordManagerPath,
+        sourcePath,
+    };
+}
+function parseRedirectPort(value, sourcePath) {
+    if (value === undefined)
+        return 8765;
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 1024 ||
+        value > 65535) {
+        throw new Error(`${sourcePath} linearOAuth.redirectPort must be an integer between 1024 and 65535.`);
+    }
+    return value;
+}
+function parseScopes(value, sourcePath) {
+    if (value === undefined)
+        return [...DEFAULT_SCOPES];
+    if (!Array.isArray(value) || !value.every((s) => typeof s === "string")) {
+        throw new Error(`${sourcePath} linearOAuth.scopes must be a string array.`);
+    }
+    return validateScopes(value);
+}
+function parsePasswordManagerPath(value, sourcePath) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${sourcePath} linearOAuth.passwordManagerPath must be a string when set.`);
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}

package/dist/commands/init/defaults.d.ts

@@ -1,5 +1,6 @@
 /**
- * Step 4 of the wizard: default labels, status defaults, term enforcement.
+ * Step 4 of the wizard: default labels, default assignee, default priority,
+ * status defaults, term enforcement, cache TTL.
  *
  * All optional. Each subsection asks "change?" with default=N so re-running
  * with no input is a no-op.
@@ -7,6 +8,19 @@
 import { type WizardConfig } from "./shared.js";
 export interface DefaultsStepResult {
     defaultLabels: string[] | undefined;
+    /**
+     * Default assignee identifier (alias / display name / email / UUID — same
+     * shapes resolveAssignee accepts) for `issues create`. The wizard does NOT
+     * validate this against Linear (no API call) — the runtime resolver handles
+     * validation at issue-create time, keeping the wizard offline.
+     */
+    defaultAssignee: string | undefined;
+    /**
+     * Default priority keyword: `none|urgent|high|medium|normal|low`. Stored
+     * as-is; the runtime path runs it through validatePriority() to get the
+     * Linear priority number.
+     */
+    defaultPriority: string | undefined;
     /**
      * Status defaults. Both fields are optional so the wizard preserves
      * partial existing configs (`{ noProject: "Backlog" }` only) byte-for-byte
@@ -21,5 +35,8 @@ export interface DefaultsStepResult {
         canonical: string;
         reject: string[];
     }> | undefined;
+    /** TTL (seconds) for `teams list` / `labels list` / `projects list` disk
+     * cache. `0` disables. */
+    cacheTTLSeconds: number | undefined;
 }
 export declare function runDefaultsStep(existing: WizardConfig): Promise<DefaultsStepResult>;

package/dist/commands/init/defaults.js

@@ -1,12 +1,22 @@
 /**
- * Step 4 of the wizard: default labels, status defaults, term enforcement.
+ * Step 4 of the wizard: default labels, default assignee, default priority,
+ * status defaults, term enforcement, cache TTL.
  *
  * All optional. Each subsection asks "change?" with default=N so re-running
  * with no input is a no-op.
  */
-import { confirm, input } from "@inquirer/prompts";
+import { confirm, input, select } from "@inquirer/prompts";
 import { parseCsvList } from "./shared.js";
 const STATUS_FALLBACK = { noProject: "Triage", withAssigneeAndProject: "Todo" };
+const CACHE_TTL_FALLBACK = 3600;
+const PRIORITY_CHOICES = [
+    { name: "none", value: "none" },
+    { name: "urgent", value: "urgent" },
+    { name: "high", value: "high" },
+    { name: "medium", value: "medium" },
+    { name: "normal", value: "normal" },
+    { name: "low", value: "low" },
+];
 export async function runDefaultsStep(existing) {
     // Idempotency rule: when the user skips a sub-section, return the existing
     // value byte-for-byte. We deliberately do NOT spread or backfill optional
@@ -14,8 +24,11 @@ export async function runDefaultsStep(existing) {
     // with no input produces a byte-identical config.
     const result = {
         defaultLabels: existing.defaultLabels,
+        defaultAssignee: existing.defaultAssignee,
+        defaultPriority: existing.defaultPriority,
         statusDefaults: existing.statusDefaults,
         terms: existing.terms,
+        cacheTTLSeconds: existing.cacheTTLSeconds,
     };
     // ── Default labels ────────────────────────────────────────────────
     const currentLabels = existing.defaultLabels ?? [];
@@ -32,6 +45,45 @@ export async function runDefaultsStep(existing) {
         const parsed = parseCsvList(raw);
         result.defaultLabels = parsed.length > 0 ? parsed : undefined;
     }
+    // ── Default assignee ──────────────────────────────────────────────
+    console.log(`  Current default assignee: ${existing.defaultAssignee ?? "(none)"}`);
+    const editAssignee = await confirm({
+        message: "Change default assignee for new issues?",
+        default: false,
+    });
+    if (editAssignee) {
+        // We deliberately don't validate against Linear here — the wizard runs
+        // offline-friendly. The runtime resolver (resolveAssignee) catches
+        // typos at issue-create time. "none" is the explicit-clear sentinel
+        // so users have an unambiguous way to wipe the field.
+        const raw = (await input({
+            message: "Default assignee (alias, name, email, or 'none' to clear):",
+            default: existing.defaultAssignee ?? "",
+        })).trim();
+        if (!raw || raw.toLowerCase() === "none") {
+            result.defaultAssignee = undefined;
+        }
+        else {
+            result.defaultAssignee = raw;
+        }
+    }
+    // ── Default priority ──────────────────────────────────────────────
+    console.log(`  Current default priority: ${existing.defaultPriority ?? "(none)"}`);
+    const editPriority = await confirm({
+        message: "Change default priority for new issues?",
+        default: false,
+    });
+    if (editPriority) {
+        // `select` always picks one option — so picking "none" stores the
+        // keyword string "none" (Linear's "No priority"), distinct from
+        // `undefined` which means "no default at all".
+        const choice = await select({
+            message: "Default priority:",
+            choices: PRIORITY_CHOICES,
+            default: existing.defaultPriority ?? "none",
+        });
+        result.defaultPriority = choice;
+    }
     // ── Status defaults ────────────────────────────────────────────────
     const cur = existing.statusDefaults;
     console.log(`  Current status defaults: noProject=${cur?.noProject ?? STATUS_FALLBACK.noProject}, ` +
@@ -54,6 +106,35 @@ export async function runDefaultsStep(existing) {
             withAssigneeAndProject: withAP.trim(),
         };
     }
+    // ── Cache TTL ─────────────────────────────────────────────────────
+    const currentTTL = existing.cacheTTLSeconds ?? CACHE_TTL_FALLBACK;
+    console.log(`  Current cache TTL: ${currentTTL}s`);
+    const editTTL = await confirm({
+        message: "Change cache TTL?",
+        default: false,
+    });
+    if (editTTL) {
+        const raw = await input({
+            message: "Cache TTL in seconds (0 to disable):",
+            default: String(currentTTL),
+            // `validate` runs per submit; we reject anything that isn't a
+            // non-negative integer literal. Number("") is `0` (truthy by
+            // the integer test) so we explicitly require non-empty input —
+            // otherwise an empty submission would silently store 0.
+            validate: (value) => {
+                const trimmed = value.trim();
+                if (trimmed === "") {
+                    return "Enter a non-negative integer (e.g. 3600 for 1 hour, 0 to disable).";
+                }
+                const n = Number(trimmed);
+                if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+                    return "Enter a non-negative integer (e.g. 3600 for 1 hour, 0 to disable).";
+                }
+                return true;
+            },
+        });
+        result.cacheTTLSeconds = Number(raw);
+    }
     // ── Term enforcement ───────────────────────────────────────────────
     const currentTerms = existing.terms ?? [];
     console.log(`  Current term-enforcement rules: ${currentTerms.length}`);

package/dist/commands/init/index.js

@@ -127,15 +127,18 @@ export function setupInitCommands(program) {
     }));
     init
         .command("defaults")
-        .description("Default labels, status defaults, term enforcement rules")
+        .description("Default labels, default assignee, default priority, status defaults, cache TTL, term enforcement")
         .action(withCleanExit(async () => {
         const existing = await readConfig();
         printStep("defaults", "Defaults");
         const result = await runDefaultsStep(existing);
         const merged = assignDefined(existing, {
             defaultLabels: result.defaultLabels,
+            defaultAssignee: result.defaultAssignee,
+            defaultPriority: result.defaultPriority,
             statusDefaults: result.statusDefaults,
             terms: result.terms,
+            cacheTTLSeconds: result.cacheTTLSeconds,
         });
         await writeConfig(merged);
         console.log("  ✓ Defaults saved.");
@@ -175,8 +178,11 @@ async function runFullWizardImpl(options) {
         // defaults step: result is `existing.X` itself when the user skipped
         // the edit branch, so direct assignment is safe.
         defaultLabels: defaults.defaultLabels,
+        defaultAssignee: defaults.defaultAssignee,
+        defaultPriority: defaults.defaultPriority,
         statusDefaults: defaults.statusDefaults,
         terms: defaults.terms,
+        cacheTTLSeconds: defaults.cacheTTLSeconds,
         // workspace step: `ws.defaultTeam` may be the existing value (user
         // skipped) or a new pick.
         defaultTeam: ws.defaultTeam,

package/dist/commands/init/oauth.d.ts

@@ -2,10 +2,10 @@
  * Wizard step for OAuth 2.0 (PKCE flow) authorization.
  *
  * Flow:
- *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
- *      app registration page. (Until we ship a shared OAuth client_id,
- *      every user registers their own app.)
- *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   1. Read optional local/team OAuth app defaults, if present.
+ *   2. Otherwise present a "what is this?" intro pointing the user at
+ *      Linear's OAuth app registration page, then prompt for `client_id`,
+ *      optional `client_secret`, port, scopes.
  *   3. Generate PKCE verifier + state, build the authorize URL.
  *   4. Try to open the system browser; fall back to printing the URL.
  *   5. Spin a localhost listener (or fall back to pasted-code prompt) to

package/dist/commands/init/oauth.js

@@ -2,10 +2,10 @@
  * Wizard step for OAuth 2.0 (PKCE flow) authorization.
  *
  * Flow:
- *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
- *      app registration page. (Until we ship a shared OAuth client_id,
- *      every user registers their own app.)
- *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   1. Read optional local/team OAuth app defaults, if present.
+ *   2. Otherwise present a "what is this?" intro pointing the user at
+ *      Linear's OAuth app registration page, then prompt for `client_id`,
+ *      optional `client_secret`, port, scopes.
  *   3. Generate PKCE verifier + state, build the authorize URL.
  *   4. Try to open the system browser; fall back to printing the URL.
  *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
@@ -19,6 +19,7 @@
  */
 import { spawn } from "node:child_process";
 import { checkbox, input, password, select } from "@inquirer/prompts";
+import { readTeamOAuthConfig } from "../../auth/oauth-app-config.js";
 import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-callback.js";
 import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateScopes, } from "../../auth/oauth-client.js";
 import { promptForPastedCode } from "../../auth/oauth-headless.js";
@@ -165,6 +166,22 @@ async function promptRegistration(defaults) {
         scopes: validateScopes(scopes),
     };
 }
+async function resolveRegistration(defaults) {
+    const teamConfig = await readTeamOAuthConfig();
+    if (!teamConfig) {
+        return promptRegistration({ port: defaults.manualPort });
+    }
+    const port = defaults.requestedPort ?? teamConfig.redirectPort;
+    logLine("");
+    logLine(TS(`Using Linear OAuth app defaults from ${teamConfig.sourcePath}.`));
+    logLine(TS(`Callback URL: http://localhost:${port}${DEFAULT_CALLBACK_PATH}`));
+    logLine("");
+    return {
+        clientId: teamConfig.clientId,
+        port,
+        scopes: teamConfig.scopes,
+    };
+}
 /**
  * Default viewer-validation routine. Calls `viewer { ... }` with the new
  * bearer token to confirm Linear accepted it. Reused for both the wizard
@@ -213,8 +230,9 @@ export async function runOAuthStep(options = {}) {
         }
         // Both `reauth` and `revoked` fall through to the re-auth flow.
     }
-    const reg = await promptRegistration({
-        port: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+    const reg = await resolveRegistration({
+        manualPort: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+        requestedPort: options.port,
     });
     const redirectUri = `http://localhost:${reg.port}${DEFAULT_CALLBACK_PATH}`;
     const pkce = generatePkce();

package/dist/commands/issues.js

@@ -263,12 +263,20 @@ function buildUpdateArgs(issueId, options, assigneeId) {
     else if (options.labels) {
         labelIds = splitList(options.labels);
     }
+    // On update, fall back to config.defaultPriority only when --priority
+    // wasn't passed. This keeps every update setting a priority for users who
+    // want a workspace-wide baseline (e.g. all unassigned triage tickets bump
+    // to "medium"). To leave priority untouched, omit defaultPriority from
+    // config — the field is opt-in.
+    const priorityInput = typeof options.priority === "string"
+        ? options.priority
+        : loadConfig().defaultPriority;
     return {
         id: issueId,
         title: options.title,
         description: options.description,
         statusId: options.status,
-        priority: options.priority ? validatePriority(options.priority) : undefined,
+        priority: priorityInput ? validatePriority(priorityInput) : undefined,
         assigneeId,
         projectId: options.project,
         labelIds,
@@ -392,6 +400,21 @@ async function handleSearchIssues(query, options, command) {
 async function resolveCreateInputs(title, options, rootOpts) {
     const config = loadConfig();
     enforceTerms([title, options.description], { strict: options.strict });
+    // Effective assignee: explicit --assignee wins; --no-assignee (commander
+    // parses as `assignee === false`) skips both flag and config; otherwise
+    // fall back to config.defaultAssignee. Computed BEFORE validation so the
+    // "assignee required" rule sees the resolved value, not undefined.
+    const noAssignee = options.assignee === false;
+    const explicitAssignee = typeof options.assignee === "string" ? options.assignee : undefined;
+    const effectiveAssignee = noAssignee
+        ? undefined
+        : (explicitAssignee ?? config.defaultAssignee);
+    // Effective priority: explicit --priority wins; otherwise fall back to
+    // config.defaultPriority. Both go through validatePriority so a bad config
+    // value fails fast with a useful error.
+    const effectivePriorityInput = typeof options.priority === "string"
+        ? options.priority
+        : config.defaultPriority;
     // --- Validation (labels, description, assignee, project, title) ---
     // Controlled by config.validation.enabled (default: true).
     // Bypassed by --skip-validation flag.
@@ -402,7 +425,7 @@ async function resolveCreateInputs(title, options, rootOpts) {
             labels: rawLabels,
             description: description || undefined,
             title,
-            assignee: options.assignee,
+            assignee: effectiveAssignee,
             project: options.project,
         });
         // Apply normalized labels back so resolution uses the canonical names
@@ -411,13 +434,13 @@ async function resolveCreateInputs(title, options, rootOpts) {
         }
         enforceValidation(validationResult);
     }
-    if (!options.priority) {
+    if (!effectivePriorityInput) {
         outputWarning("Creating issue without --priority. Consider specifying it for better triage.", "missing_fields");
     }
     const teamInput = options.team || config.defaultTeam;
     const teamId = resolveTeam(teamInput);
-    const assigneeId = options.assignee
-        ? await resolveAssignee(options.assignee, rootOpts)
+    const assigneeId = effectiveAssignee
+        ? await resolveAssignee(effectiveAssignee, rootOpts)
         : undefined;
     let labelIds = [];
     if (options.labels) {
@@ -438,7 +461,18 @@ async function resolveCreateInputs(title, options, rootOpts) {
     if (options.subscriber) {
         subscriberIds = splitList(options.subscriber).map((s) => resolveMember(s));
     }
-    return { teamInput, teamId, assigneeId, labelIds, status, subscriberIds };
+    const priority = effectivePriorityInput
+        ? validatePriority(effectivePriorityInput)
+        : undefined;
+    return {
+        teamInput,
+        teamId,
+        assigneeId,
+        labelIds,
+        status,
+        subscriberIds,
+        priority,
+    };
 }
 async function uploadAttachmentsIfNeeded(options, rootOpts) {
     if (!options.attachment) {
@@ -472,7 +506,7 @@ function buildDescriptionWithAttachments(baseDescription, uploadResults) {
 }
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
-    const { teamInput, teamId, assigneeId, labelIds, status, subscriberIds } = await resolveCreateInputs(title, options, rootOpts);
+    const { teamInput, teamId, assigneeId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title, options, rootOpts);
     const uploadResults = await uploadAttachmentsIfNeeded(options, rootOpts);
     const descriptionWithAttachments = buildDescriptionWithAttachments(resolveDescription(options) || "", uploadResults);
     // Append messageFooter (config or --footer flag) so auto-link picks up any
@@ -497,7 +531,7 @@ async function handleCreateIssue(title, options, command) {
         teamInput,
         description: prepared.description,
         assigneeId,
-        priority: options.priority ? validatePriority(options.priority) : undefined,
+        priority,
         projectId: options.project,
         statusId: status,
         labelIds: labelIds.length > 0 ? labelIds : undefined,
@@ -1075,6 +1109,7 @@ export function setupIssuesCommands(program) {
         .option("--description-file <path>", "read description from file (use - for stdin)")
         .option("--template <name>", "use a named description template from config.descriptionTemplates")
         .option("-a, --assignee <assignee>", "assign to user (name, alias, or UUID)")
+        .option("--no-assignee", "create unassigned even when config.defaultAssignee is set")
         .option("-p, --priority <priority>", "priority: name (none/urgent/high/medium/normal/low) or number (0-4)")
         .option("--project <project>", "add to project (name or ID)")
         .option("--team <team>", "team key or name (default: from config)")

package/dist/commands/labels.js

@@ -1,5 +1,7 @@
+import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.js";
 import { CREATE_LABEL_MUTATION, FIND_PARENT_LABEL_QUERY, RESTORE_LABEL_MUTATION, RETIRE_LABEL_MUTATION, } from "../queries/labels.js";
+import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
@@ -75,8 +77,19 @@ export function setupLabelsCommands(program) {
         .action(handleAsyncCommand(async (options, command) => {
         const rootOpts = getRootOpts(command);
         const teamFilter = options.team ? resolveTeam(options.team) : undefined;
-        const service = await createLinearService(rootOpts);
-        const result = await service.getLabels(teamFilter, Number.parseInt(options.limit, 10));
+        const limit = Number.parseInt(options.limit, 10);
+        const ttl = resolveCacheTTL({
+            configTTL: loadConfig().cacheTTLSeconds,
+            noCacheFlag: rootOpts.cache === false,
+        });
+        // Cache key includes the team filter so list-with-team and list-
+        // without-team don't collide. Same `limit` participates because
+        // a smaller list isn't a valid cached answer for a larger ask.
+        const cacheKey = `labels-list-team:${teamFilter ?? "_all"}-limit:${limit}`;
+        const result = await cached(cacheKey, ttl, async () => {
+            const service = await createLinearService(rootOpts);
+            return service.getLabels(teamFilter, limit);
+        });
         outputSuccess({
             data: result.labels,
             meta: { count: result.labels.length },

package/dist/commands/projects.js

@@ -1,5 +1,7 @@
+import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.js";
 import { CREATE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
+import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
@@ -305,8 +307,15 @@ export function setupProjectsCommands(program) {
         .option("--fields <fields>", "columns for table/csv (comma-separated: name,state,progress,teams,lead,targetDate)")
         .action(handleAsyncCommand(async (options, command) => {
         const rootOpts = getRootOpts(command);
-        const service = await createLinearService(rootOpts);
-        const result = await service.getProjects(Number.parseInt(options.limit, 10));
+        const limit = Number.parseInt(options.limit, 10);
+        const ttl = resolveCacheTTL({
+            configTTL: loadConfig().cacheTTLSeconds,
+            noCacheFlag: rootOpts.cache === false,
+        });
+        const result = await cached(`projects-list-limit:${limit}`, ttl, async () => {
+            const service = await createLinearService(rootOpts);
+            return service.getProjects(limit);
+        });
         const format = options.format;
         if (format === "table" ||
             format === "md" ||

package/dist/commands/teams.js

@@ -1,3 +1,5 @@
+import { loadConfig } from "../config/config.js";
+import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
@@ -13,8 +15,16 @@ export function setupTeamsCommands(program) {
         .option("-l, --limit <number>", "limit results", "100")
         .action(handleAsyncCommand(async (options, command) => {
         const rootOpts = getRootOpts(command);
-        const service = await createLinearService(rootOpts);
-        const result = await service.getTeams(Number.parseInt(options.limit, 10));
+        const limit = Number.parseInt(options.limit, 10);
+        const ttl = resolveCacheTTL({
+            configTTL: loadConfig().cacheTTLSeconds,
+            // commander's `--no-cache` produces `cache: false` on the root opts.
+            noCacheFlag: rootOpts.cache === false,
+        });
+        const result = await cached(`teams-list-limit:${limit}`, ttl, async () => {
+            const service = await createLinearService(rootOpts);
+            return service.getTeams(limit);
+        });
         outputSuccess({ data: result, meta: { count: result.length } });
     }));
 }

package/dist/config/config.d.ts

@@ -57,6 +57,25 @@ export interface ElLinearConfig {
      *   }
      */
     descriptionTemplates?: Record<string, string>;
+    /**
+     * Default assignee identifier (alias / display name / email / UUID — same
+     * shapes resolveAssignee accepts) for `issues create`. Applied when
+     * `--assignee` is not passed. Pass `--no-assignee` to override at one site.
+     */
+    defaultAssignee?: string;
+    /**
+     * Default priority for `issues create` / `issues update`. Accepts the same
+     * keywords as the --priority flag: `none|urgent|high|medium|normal|low`
+     * or `0`–`4`. Applied when `--priority` is not passed.
+     */
+    defaultPriority?: string;
+    /**
+     * TTL (seconds) for the on-disk cache used by `teams list`, `labels list`,
+     * and `projects list`. Defaults to 3600 (1 hour) when omitted. A value of
+     * `0` disables the cache entirely. Override per-invocation with
+     * `--no-cache`.
+     */
+    cacheTTLSeconds?: number;
 }
 /** Test seam — resets the cache between test cases. */
 export declare function _resetConfigCacheForTests(): void;

package/dist/config/paths.d.ts

@@ -6,6 +6,7 @@
 export declare const CONFIG_DIR: string;
 export declare const CONFIG_PATH: string;
 export declare const TOKEN_PATH: string;
+export declare const TEAM_OAUTH_CONFIG_PATH: string;
 export declare const ALIASES_PROGRESS_PATH: string;
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly

package/dist/config/paths.js

@@ -9,6 +9,7 @@ import path from "node:path";
 export const CONFIG_DIR = path.join(os.homedir(), ".config", "el-linear");
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 export const TOKEN_PATH = path.join(CONFIG_DIR, "token");
+export const TEAM_OAUTH_CONFIG_PATH = path.join(CONFIG_DIR, "team-oauth.json");
 export const ALIASES_PROGRESS_PATH = path.join(CONFIG_DIR, ".init-aliases-progress");
 /**
  * Legacy fallback paths kept for backward compatibility. The CLI was briefly

package/dist/main.js

@@ -30,13 +30,14 @@ import { splitList } from "./utils/validators.js";
 program
     .name("el-linear")
     .description("A pragmatic CLI for Linear.app — deterministic resolution, structured validation, GraphQL escape hatch.")
-    .version("1.6.0")
+    .version("1.7.0")
     .option("--api-token <token>", "Linear API token")
     .option("--profile <name>", "named profile (under ~/.config/el-linear/profiles/<name>/) for this invocation. Overrides EL_LINEAR_PROFILE env + the on-disk active-profile marker.")
     .option("--json", "output as JSON (default, accepted for compatibility)")
     .option("--raw", "strip { data, meta } wrapper from list output — emit the array directly")
     .option("--jq <filter>", "apply a jq filter to the JSON output")
-    .option("--fields <fields>", "filter output to specific fields (comma-separated)");
+    .option("--fields <fields>", "filter output to specific fields (comma-separated)")
+    .option("--no-cache", "bypass the on-disk cache for `teams list` / `labels list` / `projects list`");
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const rootOpts = actionCommand.optsWithGlobals();
     if (rootOpts.raw) {

package/dist/utils/disk-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+export interface CacheOptions {
+    /** When true, skip the read step and always refetch + rewrite. */
+    bypass?: boolean;
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export declare function cached<T>(key: string, ttlSeconds: number, fetcher: () => Promise<T>, options?: CacheOptions): Promise<T>;
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export declare function clearCache(prefix?: string): Promise<void>;
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export declare function resolveCacheTTL(args: {
+    configTTL: number | undefined;
+    noCacheFlag: boolean | undefined;
+}): number;

package/dist/utils/disk-cache.js

@@ -0,0 +1,178 @@
+/**
+ * Profile-aware disk cache with TTL. Stores JSON envelopes at
+ * `<profile-dir>/cache/<key>.json`:
+ *
+ *   { v: 1, key, fetchedAt, expiresAt, data }
+ *
+ * `cached(key, ttlSeconds, fetcher)`:
+ *   - returns cached `data` when expiresAt > now
+ *   - else awaits fetcher, writes envelope, returns fresh data
+ *   - on read error (corrupt JSON, missing dir), silently refetches
+ *
+ * Bypass:
+ *   - `bypass: true` option always refetches and rewrites (used by --no-cache)
+ *   - any error during write is logged via stderr but doesn't fail the call
+ *
+ * Eviction:
+ *   - no automatic eviction; old keys stay until manually cleared
+ *   - `clearCache(prefix?)` for tests + a future `el-linear cache clear` command
+ *
+ * Path:
+ *   - profile-aware via resolveActiveProfile() — caches don't bleed between
+ *     profiles
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveActiveProfile } from "../config/paths.js";
+const CACHE_VERSION = 1;
+const CACHE_FILE_MODE = 0o644;
+const CACHE_DIR_MODE = 0o700;
+/**
+ * Resolve `<profile-dir>/cache/`. Profile-aware so caches don't bleed
+ * across profiles. The directory of the active profile's `configPath` is
+ * the canonical "profile dir" — this matches what `commands/init/shared.ts`
+ * uses.
+ */
+function cacheDir() {
+    const active = resolveActiveProfile();
+    return path.join(path.dirname(active.configPath), "cache");
+}
+function cachePath(key) {
+    return path.join(cacheDir(), `${sanitizeKey(key)}.json`);
+}
+/**
+ * Cache keys may include filter values like `team:ENG` or `status:active`,
+ * which are POSIX-safe but we still strip path separators defensively so a
+ * malicious or buggy caller can't write outside the cache directory.
+ */
+function sanitizeKey(key) {
+    return key.replace(/[/\\\0]/g, "_");
+}
+/**
+ * Atomic write: write to a sibling tmp file then rename. Mirrors the helper
+ * in `commands/init/shared.ts` and `auth/oauth-fs.ts`. Duplicated (12 lines)
+ * to keep the dependency graph clean — the wizard depends on cache callers
+ * indirectly, so importing wizard internals here would be a cycle hazard.
+ */
+async function atomicWrite(targetPath, data) {
+    const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+    try {
+        await fs.writeFile(tmpPath, data, {
+            encoding: "utf8",
+            mode: CACHE_FILE_MODE,
+        });
+        await fs.chmod(tmpPath, CACHE_FILE_MODE);
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+async function readEnvelope(key) {
+    let raw;
+    try {
+        raw = await fs.readFile(cachePath(key), "utf8");
+    }
+    catch {
+        // Missing dir, missing file, permission errors → treat as cache miss.
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Reject envelopes from a future cache version we don't understand.
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.v !== CACHE_VERSION ||
+            typeof parsed.expiresAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        // Corrupt JSON → treat as cache miss.
+        return null;
+    }
+}
+async function writeEnvelope(key, envelope) {
+    const dir = cacheDir();
+    await fs.mkdir(dir, { recursive: true, mode: CACHE_DIR_MODE });
+    await atomicWrite(cachePath(key), JSON.stringify(envelope));
+}
+/**
+ * Read-through cache wrapper.
+ *
+ *   `key`         — stable string identifier including any filter params
+ *                   (e.g. `teams-list`, `labels-list-team:ENG`)
+ *   `ttlSeconds`  — lifetime; `0` disables the cache entirely (always
+ *                   refetch, never write).
+ *   `fetcher`     — async function returning the fresh data on a miss.
+ *   `options.bypass` — force a refetch even when an unexpired envelope
+ *                      exists. Still rewrites on success.
+ */
+export async function cached(key, ttlSeconds, fetcher, options) {
+    // TTL = 0 disables caching: never read, never write.
+    if (ttlSeconds <= 0) {
+        return fetcher();
+    }
+    const now = Date.now();
+    if (!options?.bypass) {
+        const envelope = await readEnvelope(key);
+        if (envelope && envelope.expiresAt > now) {
+            return envelope.data;
+        }
+    }
+    const data = await fetcher();
+    const envelope = {
+        v: CACHE_VERSION,
+        key,
+        fetchedAt: now,
+        expiresAt: now + ttlSeconds * 1000,
+        data,
+    };
+    try {
+        await writeEnvelope(key, envelope);
+    }
+    catch (err) {
+        // Cache writes are best-effort — log to stderr and return the data
+        // anyway so a flaky disk doesn't break the user's command.
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[disk-cache] write failed for "${key}": ${msg}\n`);
+    }
+    return data;
+}
+/**
+ * Clear cached entries. With no `prefix`, removes the entire cache
+ * directory. With a `prefix`, only deletes envelopes whose sanitized key
+ * starts with it. Errors (missing dir, permission) are swallowed so this is
+ * safe to call from tests.
+ */
+export async function clearCache(prefix) {
+    const dir = cacheDir();
+    if (!prefix) {
+        await fs.rm(dir, { recursive: true, force: true });
+        return;
+    }
+    const sanitized = sanitizeKey(prefix);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries
+        .filter((name) => name.endsWith(".json") && name.startsWith(sanitized))
+        .map((name) => fs.unlink(path.join(dir, name)).catch(() => { })));
+}
+/** Resolved cache TTL for command call sites: respects --no-cache + config. */
+export function resolveCacheTTL(args) {
+    if (args.noCacheFlag) {
+        return 0;
+    }
+    if (args.configTTL === undefined) {
+        return 3600;
+    }
+    return args.configTTL;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",