fix: error when --workspace flag specifies unknown workspace

Previously, --workspace would silently fall back to other credential
sources when the specified workspace wasn't found. Now it errors with
a helpful message suggesting `linear auth login` or `linear auth list`.

Also errors when both LINEAR_API_KEY env var and --workspace are set,
since these are conflicting ways to specify credentials.

Added error handling guidelines to CLAUDE.md to prevent silent failures.

Author: schpet

CLAUDE.md

@@ -15,6 +15,12 @@
 - see [docs/deno-permissions.md](docs/deno-permissions.md) for the full list of files to update when adding new permissions
 - key files: `deno.json` (tasks), `dist-workspace.toml` (release builds), test files
 
+## error handling
+
+- never fail silently - if something goes wrong or a lookup fails, throw an error with a helpful message
+- when user-provided input (flags, args) doesn't match expected values, error immediately with guidance on how to fix it
+- avoid falling back to defaults when explicit user input is invalid; explicit input should either work or error
+
 ## tests
 
 - tests on commands should mirror the directory structure of the src, e.g.

src/utils/graphql.ts

@@ -38,35 +38,54 @@ export function logClientError(error: ClientError): void {
 
 /**
  * Get the resolved API key following the precedence chain:
- * 1. --api-key CLI flag (explicit key)
- * 2. LINEAR_API_KEY env var
- * 3. api_key in project config
- * 4. --workspace flag → credentials lookup
- * 5. Project's workspace config → credentials lookup
- * 6. default workspace from credentials file
+ * 1. LINEAR_API_KEY env var (conflicts with --workspace)
+ * 2. api_key in project config
+ * 3. --workspace flag → credentials lookup
+ * 4. Project's workspace config → credentials lookup
+ * 5. default workspace from credentials file
  */
 export function getResolvedApiKey(): string | undefined {
-  // 1-3: Check existing sources (CLI flag, env var, project config)
+  const cliWorkspace = getCliWorkspace()
+  const envApiKey = Deno.env.get("LINEAR_API_KEY")
+
+  // Error if both LINEAR_API_KEY and --workspace are set
+  if (envApiKey && cliWorkspace) {
+    throw new Error(
+      "Cannot use --workspace flag when LINEAR_API_KEY environment variable is set. " +
+        "Either unset LINEAR_API_KEY or remove the --workspace flag.",
+    )
+  }
+
+  // 1: LINEAR_API_KEY env var
+  if (envApiKey) {
+    return envApiKey
+  }
+
+  // 2: api_key in project config
   const configApiKey = getOption("api_key")
   if (configApiKey) {
     return configApiKey
   }
 
-  // 4: --workspace flag → credentials lookup
-  const cliWorkspace = getCliWorkspace()
+  // 3: --workspace flag → credentials lookup
   if (cliWorkspace) {
     const key = getCredentialApiKey(cliWorkspace)
     if (key) return key
+    // Explicit --workspace flag must match a configured workspace
+    throw new Error(
+      `Workspace "${cliWorkspace}" not found in credentials. ` +
+        `Run \`linear auth login\` to add it, or \`linear auth list\` to see configured workspaces.`,
+    )
   }
 
-  // 5: Project's workspace config → credentials lookup
+  // 4: Project's workspace config → credentials lookup
   const projectWorkspace = getOption("workspace")
   if (projectWorkspace) {
     const key = getCredentialApiKey(projectWorkspace)
     if (key) return key
   }
 
-  // 6: Default workspace from credentials file
+  // 5: Default workspace from credentials file
   return getCredentialApiKey()
 }
 

test/utils/graphql.test.ts

@@ -0,0 +1,55 @@
+import { assertEquals, assertStringIncludes, assertThrows } from "@std/assert"
+import { setCliWorkspace } from "../../src/config.ts"
+import { getResolvedApiKey } from "../../src/utils/graphql.ts"
+
+Deno.test("getResolvedApiKey - errors when --workspace not found in credentials", () => {
+  // Setup - use a workspace name that definitely doesn't exist
+  Deno.env.delete("LINEAR_API_KEY")
+  setCliWorkspace("nonexistent-workspace-xyz-123")
+
+  try {
+    const error = assertThrows(
+      () => getResolvedApiKey(),
+      Error,
+    )
+    assertStringIncludes(
+      error.message,
+      'Workspace "nonexistent-workspace-xyz-123" not found in credentials',
+    )
+  } finally {
+    // Cleanup
+    setCliWorkspace(undefined)
+  }
+})
+
+Deno.test("getResolvedApiKey - errors when LINEAR_API_KEY and --workspace both set", () => {
+  // Setup
+  Deno.env.set("LINEAR_API_KEY", "test-api-key")
+  setCliWorkspace("test-workspace")
+
+  try {
+    assertThrows(
+      () => getResolvedApiKey(),
+      Error,
+      "Cannot use --workspace flag when LINEAR_API_KEY environment variable is set",
+    )
+  } finally {
+    // Cleanup
+    Deno.env.delete("LINEAR_API_KEY")
+    setCliWorkspace(undefined)
+  }
+})
+
+Deno.test("getResolvedApiKey - returns LINEAR_API_KEY when set without --workspace", () => {
+  // Setup
+  Deno.env.set("LINEAR_API_KEY", "test-api-key")
+  setCliWorkspace(undefined)
+
+  try {
+    const result = getResolvedApiKey()
+    assertEquals(result, "test-api-key")
+  } finally {
+    // Cleanup
+    Deno.env.delete("LINEAR_API_KEY")
+  }
+})