@pilatos/bitbucket-cli 1.14.0 → 1.15.0

package/README.md

@@ -47,15 +47,28 @@
 
 ## Install
 
-```bash
-npm install -g @pilatos/bitbucket-cli
-```
+> **Requires:** [Bun](https://bun.sh) runtime 1.0 or higher. The CLI is installed via npm but runs on the Bun runtime — Node.js is not supported.
 
-```bash
-bb --version
-```
+1. **Install Bun** (if `bun --version` fails):
+
+   ```bash
+   curl -fsSL https://bun.sh/install | bash
+   ```
+
+2. **Install the CLI:**
 
-> **Requires:** [Bun](https://bun.sh) runtime 1.0 or higher. The CLI is installed via npm but runs on the Bun runtime — Node.js is not supported. Install Bun first: `curl -fsSL https://bun.sh/install | bash`
+   ```bash
+   npm install -g @pilatos/bitbucket-cli
+   bb --version
+   ```
+
+3. **Tab completion** (optional, recommended):
+
+   ```bash
+   bb completion install
+   ```
+
+   Then restart your shell.
 
 ---
 
@@ -78,7 +91,21 @@ bb pr approve 42
 bb config set defaultWorkspace myworkspace
 ```
 
-**Global options:** `--json`, `--no-color`, `-w, --workspace`, `-r, --repo`
+**Global options:** `--json [fields]`, `--jq <expression>`, `--no-color`, `-w, --workspace`, `-r, --repo`
+
+### Scripting with `--json` and `--jq`
+
+`--json` accepts an optional comma-separated field list to project the output, and `--jq` filters the JSON in-process (no external `jq` binary required):
+
+```bash
+# Project to specific fields
+bb pr list --json id,title,state
+
+# Filter through built-in jq
+bb pr list --json --jq '.pullRequests[] | select(.state == "OPEN") | .title'
+```
+
+See [JSON Output](https://bitbucket-cli.paulvanderlei.com/reference/json-output/) and the [Scripting guide](https://bitbucket-cli.paulvanderlei.com/guides/scripting/) for more.
 
 ---
 
@@ -89,6 +116,8 @@ Full documentation: **[bitbucket-cli.paulvanderlei.com](https://bitbucket-cli.pa
 - [Quick Start Guide](https://bitbucket-cli.paulvanderlei.com/getting-started/quickstart/)
 - [Command Reference](https://bitbucket-cli.paulvanderlei.com/commands/auth/)
 - [Guides](https://bitbucket-cli.paulvanderlei.com/guides/scripting/) (Scripting, CI/CD)
+- AI assistant integration (Claude Code, Cursor, Windsurf): see [Guides &gt; AI Agents](https://bitbucket-cli.paulvanderlei.com/guides/ai-agents/)
+- [Changelog](https://bitbucket-cli.paulvanderlei.com/help/changelog/) — what's new in recent releases
 - [Help](https://bitbucket-cli.paulvanderlei.com/help/troubleshooting/) (Troubleshooting, FAQ)
 
 ---
@@ -102,6 +131,20 @@ Full documentation: **[bitbucket-cli.paulvanderlei.com](https://bitbucket-cli.pa
 
 ---
 
+## Environment Variables
+
+| Variable       | Description                                                |
+| -------------- | ---------------------------------------------------------- |
+| `BB_USERNAME`  | Bitbucket username (fallback for `bb auth login`)          |
+| `BB_API_TOKEN` | Bitbucket API token (fallback for `bb auth login`; for CI) |
+| `DEBUG`        | Enable HTTP debug logging when set to `true`               |
+| `NO_COLOR`     | Disable color output when set                              |
+| `FORCE_COLOR`  | Force color output when set (and not `0`)                  |
+
+Full reference: [Environment variables](https://bitbucket-cli.paulvanderlei.com/reference/environment-variables/).
+
+---
+
 ## Contributing
 
 Read the [Contributing Guide](CONTRIBUTING.md) to get started.

package/dist/index.js

@@ -17483,6 +17483,7 @@ var ServiceTokens = {
 // src/services/config.service.ts
 import { posix, win32 } from "path";
 import { homedir } from "os";
+import { randomUUID } from "crypto";
 
 // src/types/errors.ts
 class BBError extends Error {
@@ -17531,6 +17532,12 @@ class APIError extends BBError {
     }
   }
 }
+function rethrowWithNotFoundContext(error, notFoundMessage) {
+  if (error instanceof APIError && error.statusCode === 404) {
+    throw new APIError(notFoundMessage, 404, error.response, error.context);
+  }
+  throw error;
+}
 
 class GitError extends BBError {
   command;
@@ -17548,13 +17555,19 @@ class GitError extends BBError {
 }
 
 // src/services/config.service.ts
+var CONFIG_FILE_MODE = 384;
+var CONFIG_DIR_MODE = 448;
+var INSECURE_MODE_MASK = 63;
+
 class ConfigService {
   configDir;
   configFile;
+  platform;
   configCache = null;
   constructor(configDir, options = {}) {
     const platform = options.platform ?? process.platform;
     const joinPath = platform === "win32" ? win32.join : posix.join;
+    this.platform = platform;
     this.configDir = configDir ?? this.resolveDefaultConfigDir({ ...options, platform });
     this.configFile = joinPath(this.configDir, "config.json");
   }
@@ -17575,7 +17588,10 @@ class ConfigService {
   async ensureConfigDir() {
     try {
       const fs = await import("fs/promises");
-      await fs.mkdir(this.configDir, { recursive: true });
+      await fs.mkdir(this.configDir, {
+        recursive: true,
+        mode: CONFIG_DIR_MODE
+      });
     } catch (error) {
       throw new BBError({
         code: 4002 /* CONFIG_WRITE_FAILED */,
@@ -17584,12 +17600,36 @@ class ConfigService {
       });
     }
   }
+  async verifyPermissions(path, expectedMode, kind) {
+    if (this.platform === "win32")
+      return;
+    const fs = await import("fs/promises");
+    let stats;
+    try {
+      stats = await fs.stat(path);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return;
+      throw error;
+    }
+    const mode = stats.mode & 511;
+    if (mode & INSECURE_MODE_MASK) {
+      const actual = mode.toString(8).padStart(3, "0");
+      const expected = expectedMode.toString(8).padStart(3, "0");
+      throw new BBError({
+        code: 4001 /* CONFIG_READ_FAILED */,
+        message: `Config ${kind} has insecure permissions (${actual}); expected ${expected}. Run: chmod ${expected} ${path}`
+      });
+    }
+  }
   async getConfig() {
     if (this.configCache) {
       return this.configCache;
     }
     try {
       const fs = await import("fs/promises");
+      await this.verifyPermissions(this.configDir, CONFIG_DIR_MODE, "directory");
+      await this.verifyPermissions(this.configFile, CONFIG_FILE_MODE, "file");
       const data = await fs.readFile(this.configFile, "utf-8");
       this.configCache = JSON.parse(data);
       return this.configCache;
@@ -17598,6 +17638,9 @@ class ConfigService {
         this.configCache = {};
         return this.configCache;
       }
+      if (error instanceof BBError) {
+        throw error;
+      }
       throw new BBError({
         code: 4001 /* CONFIG_READ_FAILED */,
         message: `Failed to read config file: ${this.configFile}`,
@@ -17607,13 +17650,20 @@ class ConfigService {
   }
   async setConfig(config) {
     await this.ensureConfigDir();
+    const fs = await import("fs/promises");
+    const body = JSON.stringify(config, null, 2);
+    const tmpFile = `${this.configFile}.${randomUUID()}.tmp`;
     try {
-      const fs = await import("fs/promises");
-      await fs.writeFile(this.configFile, JSON.stringify(config, null, 2), {
-        mode: 384
+      await fs.writeFile(tmpFile, body, {
+        mode: CONFIG_FILE_MODE,
+        flag: "wx"
       });
+      await fs.rename(tmpFile, this.configFile);
       this.configCache = config;
     } catch (error) {
+      try {
+        await fs.unlink(tmpFile);
+      } catch {}
       throw new BBError({
         code: 4002 /* CONFIG_WRITE_FAILED */,
         message: `Failed to write config file: ${this.configFile}`,
@@ -17627,7 +17677,7 @@ class ConfigService {
     if (!username || !apiToken) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "Authentication required. Run 'bb auth login' to authenticate."
+        message: "Authentication required. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     return { username, apiToken };
@@ -17674,7 +17724,7 @@ class ConfigService {
     if (!oauthAccessToken || !oauthRefreshToken || !oauthExpiresAt) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "OAuth authentication required. Run 'bb auth login' to authenticate."
+        message: "OAuth authentication required. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     return {
@@ -17797,14 +17847,14 @@ class ContextService {
     this.configService = configService;
   }
   parseRemoteUrl(url) {
-    const sshMatch = /git@bitbucket\.org:([^/]+)\/([^.]+)(?:\.git)?/.exec(url);
+    const sshMatch = /^git@bitbucket\.org:([^/\s]+)\/([^/\s.]+)(?:\.git)?$/.exec(url);
     if (sshMatch) {
       return {
         workspace: sshMatch[1],
         repoSlug: sshMatch[2]
       };
     }
-    const httpsMatch = /https?:\/\/(?:[^@]+@)?bitbucket\.org\/([^/]+)\/([^/.]+)(?:\.git)?/.exec(url);
+    const httpsMatch = /^https?:\/\/(?:[^@\s]+@)?bitbucket\.org\/([^/\s]+)\/([^/\s.]+)(?:\.git)?$/.exec(url);
     if (httpsMatch) {
       return {
         workspace: httpsMatch[1],
@@ -17814,29 +17864,48 @@ class ContextService {
     return null;
   }
   async getRepoContextFromGit() {
+    const result = await this.inspectGitRepoContext();
+    return result.context;
+  }
+  async inspectGitRepoContext() {
     const isRepo = await this.gitService.isRepository();
     if (!isRepo) {
-      return null;
+      return { context: null, reason: "not_a_git_repo", remoteUrl: null };
     }
+    let remoteUrl;
     try {
-      const remoteUrl = await this.gitService.getRemoteUrl();
-      return this.parseRemoteUrl(remoteUrl);
+      remoteUrl = await this.gitService.getRemoteUrl();
     } catch {
-      return null;
+      return { context: null, reason: "no_remote", remoteUrl: null };
     }
+    const context = this.parseRemoteUrl(remoteUrl);
+    if (!context) {
+      return { context: null, reason: "remote_not_bitbucket", remoteUrl };
+    }
+    return { context, reason: null, remoteUrl };
   }
   async getRepoContext(options) {
+    const result = await this.resolveRepoContext(options);
+    return result.context;
+  }
+  async resolveRepoContext(options) {
     if (options.workspace && options.repo) {
       return {
-        workspace: options.workspace,
-        repoSlug: options.repo
+        context: { workspace: options.workspace, repoSlug: options.repo },
+        reason: null,
+        remoteUrl: null
       };
     }
-    const gitContext = await this.getRepoContextFromGit();
+    const gitResult = await this.inspectGitRepoContext();
+    const gitContext = gitResult.context;
     if (options.workspace && gitContext) {
       return {
-        workspace: options.workspace,
-        repoSlug: gitContext.repoSlug
+        context: {
+          workspace: options.workspace,
+          repoSlug: gitContext.repoSlug
+        },
+        reason: null,
+        remoteUrl: gitResult.remoteUrl
       };
     }
     if (options.repo) {
@@ -17844,22 +17913,40 @@ class ContextService {
       const workspace = gitContext?.workspace || config.defaultWorkspace;
       if (workspace) {
         return {
-          workspace,
-          repoSlug: options.repo
+          context: { workspace, repoSlug: options.repo },
+          reason: null,
+          remoteUrl: gitResult.remoteUrl
         };
       }
     }
-    return gitContext;
+    return gitResult;
   }
   async requireRepoContext(options) {
-    const context = await this.getRepoContext(options);
-    if (!context) {
+    const result = await this.resolveRepoContext(options);
+    if (!result.context) {
       throw new BBError({
         code: 6001 /* CONTEXT_REPO_NOT_FOUND */,
-        message: "Could not determine repository. Use --workspace and --repo options, " + "or run this command from within a Bitbucket repository."
+        message: this.buildRepoNotFoundMessage(result.reason, result.remoteUrl),
+        context: {
+          reason: result.reason ?? "unknown",
+          ...result.remoteUrl ? { remoteUrl: result.remoteUrl } : {}
+        }
       });
     }
-    return context;
+    return result.context;
+  }
+  buildRepoNotFoundMessage(reason, remoteUrl) {
+    const fallback = "Use --workspace and --repo options, or run this command from within a Bitbucket repository.";
+    switch (reason) {
+      case "not_a_git_repo":
+        return `Not in a git repository. ${fallback}`;
+      case "no_remote":
+        return `Git repository has no remote configured. Add a Bitbucket remote with \`git remote add origin <url>\`, or ${fallback.charAt(0).toLowerCase()}${fallback.slice(1)}`;
+      case "remote_not_bitbucket":
+        return `Remote ${remoteUrl ? `'${remoteUrl}' ` : ""}is not a Bitbucket URL. ${fallback}`;
+      default:
+        return `Could not determine repository. ${fallback}`;
+    }
   }
   async requireWorkspace(explicit) {
     if (explicit && explicit.length > 0) {
@@ -18397,6 +18484,10 @@ function deepGet(source, path) {
 }
 
 // src/services/output.service.ts
+var CONTROL_CHARS = /(\x1b\[[0-9;?]*m)|\x1b\[[0-9;?]*[A-Za-ln-z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x9B\x9D]/g;
+function stripControl(value) {
+  return value.replace(CONTROL_CHARS, (_match, sgr) => sgr ?? "");
+}
 var WRAPPER_ARRAY_KEYS = [
   "pullRequests",
   "repositories",
@@ -18442,36 +18533,38 @@ class OutputService {
     if (rows.length === 0) {
       return;
     }
-    const widths = headers.map((header, index) => {
-      const maxRowWidth = Math.max(...rows.map((row) => (row[index] || "").length));
+    const sanitizedHeaders = headers.map(stripControl);
+    const sanitizedRows = rows.map((row) => row.map((cell) => stripControl(cell || "")));
+    const widths = sanitizedHeaders.map((header, index) => {
+      const maxRowWidth = Math.max(...sanitizedRows.map((row) => (row[index] || "").length));
       return Math.max(header.length, maxRowWidth);
     });
-    const headerRow = headers.map((header, index) => header.padEnd(widths[index])).join("  ");
+    const headerRow = sanitizedHeaders.map((header, index) => header.padEnd(widths[index])).join("  ");
     console.log(this.format(headerRow, source_default.bold));
     console.log(widths.map((width) => "-".repeat(width)).join("  "));
-    for (const row of rows) {
-      const formattedRow = row.map((cell, index) => (cell || "").padEnd(widths[index])).join("  ");
+    for (const row of sanitizedRows) {
+      const formattedRow = row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
       console.log(formattedRow);
     }
   }
   success(message) {
     const symbol = this.format("\u2713", source_default.green);
-    console.log(`${symbol} ${message}`);
+    console.log(`${symbol} ${stripControl(message)}`);
   }
   error(message) {
     const symbol = this.format("\u2717", source_default.red);
-    console.error(`${symbol} ${message}`);
+    console.error(`${symbol} ${stripControl(message)}`);
   }
   warning(message) {
     const symbol = this.format("\u26A0", source_default.yellow);
-    console.warn(`${symbol} ${message}`);
+    console.warn(`${symbol} ${stripControl(message)}`);
   }
   info(message) {
     const symbol = this.format("\u2139", source_default.blue);
-    console.log(`${symbol} ${message}`);
+    console.log(`${symbol} ${stripControl(message)}`);
   }
   text(message) {
-    console.log(message);
+    console.log(stripControl(message));
   }
   formatDate(date) {
     const d = typeof date === "string" ? new Date(date) : date;
@@ -22485,6 +22578,17 @@ function getRetryDelay(error, attempt) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function redactRequestUrl(requestUrl, baseUrl) {
+  const raw = requestUrl ?? "";
+  try {
+    const parsed = new URL(raw, baseUrl);
+    const query = parsed.search ? "?[redacted]" : "";
+    return `${parsed.origin}${parsed.pathname}${query}`;
+  } catch {
+    const queryIdx = raw.indexOf("?");
+    return queryIdx === -1 ? raw : `${raw.slice(0, queryIdx)}?[redacted]`;
+  }
+}
 function createApiClient(credentialStore, oauthService) {
   const instance = axios_default.create({
     baseURL: BASE_URL,
@@ -22495,7 +22599,7 @@ function createApiClient(credentialStore, oauthService) {
   });
   instance.interceptors.request.use(async (config) => {
     if (process.env.DEBUG === "true") {
-      console.debug(`[HTTP] ${config.method?.toUpperCase()} ${config.url}`);
+      console.debug(`[HTTP] ${config.method?.toUpperCase()} ${redactRequestUrl(config.url, config.baseURL)}`);
     }
     const authMethod = await credentialStore.getAuthMethod();
     if (authMethod === "oauth" && oauthService) {
@@ -22558,11 +22662,17 @@ function createApiClient(credentialStore, oauthService) {
     if (error.response) {
       const { status, data } = error.response;
       const message = extractErrorMessage(data) || error.message;
-      throw new APIError(message, status, data);
+      const method = error.config?.method?.toUpperCase();
+      const url2 = error.config?.url;
+      throw new APIError(message, status, data, {
+        status,
+        ...method ? { method } : {},
+        ...url2 ? { url: url2 } : {}
+      });
     } else if (error.request) {
       throw new BBError({
         code: 7001 /* NETWORK_ERROR */,
-        message: "Network error: Unable to reach Bitbucket API",
+        message: "Network error: Unable to reach Bitbucket API. Run with DEBUG=true for details. If you're behind a proxy or using a custom CA, check your environment.",
         cause: error
       });
     } else {
@@ -22592,13 +22702,15 @@ function extractErrorMessage(data) {
 }
 // src/services/oauth.service.ts
 import { createServer } from "http";
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
 var BITBUCKET_AUTHORIZE_URL = "https://bitbucket.org/site/oauth2/authorize";
 var BITBUCKET_TOKEN_URL = "https://bitbucket.org/site/oauth2/access_token";
+var CALLBACK_HOST = "127.0.0.1";
 var CALLBACK_PORT = 19872;
 var CALLBACK_PATH = "/callback";
 var CALLBACK_URL = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
 var AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 1e4;
 var DEFAULT_CLIENT_ID = "ErUBvNmdYtfVHgW6J4";
 var DEFAULT_CLIENT_SECRET = "QnrWypuKXv7YvU7WJwQRza2n2QfHCEw5";
 var OAUTH_SCOPES = [
@@ -22609,7 +22721,36 @@ var OAUTH_SCOPES = [
   "pullrequest:write"
 ].join(" ");
 function generateState() {
-  return randomBytes(16).toString("hex");
+  return randomBytes(32).toString("hex");
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generatePkcePair() {
+  const verifier = base64UrlEncode(randomBytes(32));
+  const challenge = base64UrlEncode(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+var OAUTH_ERROR_DESCRIPTION_MAX_LENGTH = 200;
+function extractOAuthErrorDescription(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("error_description" in parsed)) {
+    return;
+  }
+  const description = parsed.error_description;
+  if (typeof description !== "string") {
+    return;
+  }
+  const sanitized = description.replace(/\s+/g, " ").trim();
+  if (sanitized.length === 0) {
+    return;
+  }
+  return sanitized.length > OAUTH_ERROR_DESCRIPTION_MAX_LENGTH ? `${sanitized.slice(0, OAUTH_ERROR_DESCRIPTION_MAX_LENGTH)}\u2026` : sanitized;
 }
 
 class OAuthService {
@@ -22622,9 +22763,10 @@ class OAuthService {
   async authorize(clientId, clientSecret) {
     const resolvedClientId = clientId ?? await this.getClientId();
     const state = generateState();
-    const authUrl = this.buildAuthUrl(resolvedClientId, state);
+    const { verifier, challenge } = generatePkcePair();
+    const authUrl = this.buildAuthUrl(resolvedClientId, state, challenge);
     const { code } = await this.waitForCallback(authUrl, state);
-    const tokenResponse = await this.exchangeCode(code, resolvedClientId, clientSecret);
+    const tokenResponse = await this.exchangeCode(code, resolvedClientId, verifier, clientSecret);
     const expiresAt = Math.floor(Date.now() / 1000) + tokenResponse.expires_in;
     await this.credentialStore.setOAuthCredentials({
       accessToken: tokenResponse.access_token,
@@ -22654,14 +22796,17 @@ class OAuthService {
         "Content-Type": "application/x-www-form-urlencoded",
         Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
       },
-      body: params.toString()
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       const errorBody = await response.text();
+      const description = extractOAuthErrorDescription(errorBody);
+      const baseMessage = `Failed to refresh OAuth token. Run 'bb auth login' to re-authenticate.`;
       throw new BBError({
         code: 1003 /* AUTH_EXPIRED */,
-        message: `Failed to refresh OAuth token. Run 'bb auth login' to re-authenticate.`,
-        context: { status: response.status, body: errorBody }
+        message: description ? `${baseMessage} (${description})` : baseMessage,
+        context: { status: response.status }
       });
     }
     const tokenResponse = await response.json();
@@ -22674,22 +22819,29 @@ class OAuthService {
     return tokenResponse.access_token;
   }
   async revokeToken() {
-    try {
-      const credentials = await this.credentialStore.getOAuthCredentials();
-      const clientId = await this.getClientId();
-      const clientSecret = await this.getClientSecret();
-      const params = new URLSearchParams({
-        token: credentials.accessToken
-      });
-      await fetch("https://bitbucket.org/site/oauth2/revoke", {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/x-www-form-urlencoded",
-          Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
-        },
-        body: params.toString()
+    const credentials = await this.credentialStore.getOAuthCredentials();
+    const clientId = await this.getClientId();
+    const clientSecret = await this.getClientSecret();
+    const params = new URLSearchParams({
+      token: credentials.accessToken
+    });
+    const response = await fetch("https://bitbucket.org/site/oauth2/revoke", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
+      },
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "");
+      throw new BBError({
+        code: 7001 /* NETWORK_ERROR */,
+        message: `Failed to revoke OAuth token (HTTP ${response.status}).`,
+        context: { status: response.status, body: errorBody }
       });
-    } catch {}
+    }
   }
   async getValidAccessToken() {
     const isExpired = await this.credentialStore.isOAuthTokenExpired();
@@ -22707,13 +22859,15 @@ class OAuthService {
     const customSecret = await this.configService.getValue("oauthClientSecret");
     return customSecret ?? DEFAULT_CLIENT_SECRET;
   }
-  buildAuthUrl(clientId, state) {
+  buildAuthUrl(clientId, state, codeChallenge) {
     const params = new URLSearchParams({
       client_id: clientId,
       response_type: "code",
       redirect_uri: CALLBACK_URL,
       scope: OAUTH_SCOPES,
-      state
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
     });
     return `${BITBUCKET_AUTHORIZE_URL}?${params.toString()}`;
   }
@@ -22783,7 +22937,7 @@ class OAuthService {
           }));
         }
       });
-      server.listen(CALLBACK_PORT, async () => {
+      server.listen(CALLBACK_PORT, CALLBACK_HOST, async () => {
         try {
           const open2 = (await Promise.resolve().then(() => (init_open(), exports_open))).default;
           await open2(authUrl);
@@ -22794,12 +22948,13 @@ ${authUrl}
       });
     });
   }
-  async exchangeCode(code, clientId, clientSecretOverride) {
+  async exchangeCode(code, clientId, codeVerifier, clientSecretOverride) {
     const clientSecret = clientSecretOverride ?? await this.getClientSecret();
     const params = new URLSearchParams({
       grant_type: "authorization_code",
       code,
-      redirect_uri: CALLBACK_URL
+      redirect_uri: CALLBACK_URL,
+      code_verifier: codeVerifier
     });
     const response = await fetch(BITBUCKET_TOKEN_URL, {
       method: "POST",
@@ -22807,21 +22962,25 @@ ${authUrl}
         "Content-Type": "application/x-www-form-urlencoded",
         Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`
       },
-      body: params.toString()
+      body: params.toString(),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       const errorBody = await response.text();
+      const description = extractOAuthErrorDescription(errorBody);
+      const baseMessage = `Failed to exchange authorization code. Please try again.`;
       throw new BBError({
         code: 1002 /* AUTH_INVALID */,
-        message: `Failed to exchange authorization code. Please try again.`,
-        context: { status: response.status, body: errorBody }
+        message: description ? `${baseMessage} (${description})` : baseMessage,
+        context: { status: response.status }
       });
     }
     return await response.json();
   }
   async fetchUserInfo(accessToken) {
     const response = await fetch("https://api.bitbucket.org/2.0/user", {
-      headers: { Authorization: `Bearer ${accessToken}` }
+      headers: { Authorization: `Bearer ${accessToken}` },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
     });
     if (!response.ok) {
       throw new BBError({
@@ -27005,13 +27164,32 @@ class BaseCommand {
   }
   requireOption(value, name, message) {
     if (value === undefined || value === null || value === "") {
+      const baseMessage = message || `Option --${name} is required`;
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: message || `Option --${name} is required`
+        message: this.appendHelpHint(baseMessage)
       });
     }
     return value;
   }
+  appendHelpHint(message) {
+    const commandPath = this.getCommandPath();
+    const target = commandPath ? `bb ${commandPath} --help` : "bb --help";
+    return `${message} Run \`${target}\` for usage.`;
+  }
+  getCommandPath() {
+    const argv = process.argv.slice(2);
+    const tokens = [];
+    for (const arg of argv) {
+      if (arg.startsWith("-"))
+        break;
+      tokens.push(arg);
+    }
+    if (tokens.length >= 2) {
+      return `${tokens[0]} ${tokens[1]}`;
+    }
+    return tokens.join(" ");
+  }
   parseIntOption(value, name) {
     const parsed = Number.parseInt(value, 10);
     if (Number.isNaN(parsed)) {
@@ -27112,12 +27290,33 @@ class LoginCommand extends BaseCommand {
       this.output.success(`Logged in as ${user.display_name} (${user.username})`);
     } catch (error) {
       await this.credentialStore.clearCredentials();
-      throw new BBError({
-        code: 1002 /* AUTH_INVALID */,
-        message: `Authentication failed: ${error instanceof Error ? error.message : String(error)}`
-      });
+      throw this.wrapLoginError(error);
     }
   }
+  wrapLoginError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof APIError) {
+      if (error.statusCode === 401 || error.statusCode === 403) {
+        return new BBError({
+          code: 1002 /* AUTH_INVALID */,
+          message: `Invalid username or token: ${detail}. Verify your Bitbucket username and that the API token is current and has the required scopes.`,
+          cause: error
+        });
+      }
+      if (error.statusCode === 429) {
+        return new BBError({
+          code: 2004 /* API_RATE_LIMITED */,
+          message: `Bitbucket API rate-limited: ${detail}. Wait a moment and try again.`,
+          cause: error
+        });
+      }
+    }
+    return new BBError({
+      code: 1002 /* AUTH_INVALID */,
+      message: `Authentication failed: ${detail}`,
+      cause: error instanceof Error ? error : undefined
+    });
+  }
 }
 
 // src/commands/auth/logout.command.ts
@@ -27133,16 +27332,28 @@ class LogoutCommand extends BaseCommand {
   }
   async execute(_options, context) {
     const authMethod = await this.credentialStore.getAuthMethod();
+    let revokeFailed = false;
     if (authMethod === "oauth") {
-      await this.oauthService.revokeToken();
+      try {
+        await this.oauthService.revokeToken();
+      } catch {
+        revokeFailed = true;
+      }
       await this.credentialStore.clearOAuthCredentials();
     } else {
       await this.credentialStore.clearCredentials();
     }
     if (context.globalOptions.json) {
-      await this.output.json({ authenticated: false, success: true });
+      await this.output.json({
+        authenticated: false,
+        success: true,
+        revokeFailed: revokeFailed || undefined
+      });
       return;
     }
+    if (revokeFailed) {
+      this.output.warning("Token revocation failed; the access token may still be valid at Bitbucket. Consider revoking it manually.");
+    }
     this.output.success("Logged out of Bitbucket");
   }
 }
@@ -27252,7 +27463,7 @@ class TokenCommand extends BaseCommand {
     if (!credentials.username || !credentials.apiToken) {
       throw new BBError({
         code: 1001 /* AUTH_REQUIRED */,
-        message: "Not authenticated. Run 'bb auth login' first."
+        message: "Not authenticated. Run 'bb auth login' or set BB_USERNAME and BB_API_TOKEN."
       });
     }
     const token = Buffer.from(`${credentials.username}:${credentials.apiToken}`).toString("base64");
@@ -27729,7 +27940,7 @@ class ViewRepoCommand extends BaseCommand {
     const response = await this.repositoriesApi.repositoriesWorkspaceRepoSlugGet({
       workspace: repoContext.workspace,
       repoSlug: repoContext.repoSlug
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Repository ${repoContext.workspace}/${repoContext.repoSlug} not found.`));
     const repo = response.data;
     if (context.globalOptions.json) {
       await this.output.json(repo);
@@ -27952,7 +28163,7 @@ class CreatePRCommand extends BaseCommand {
     if (!options.title) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "Pull request title is required. Use --title option."
+        message: this.appendHelpHint("Pull request title is required. Use --title option.")
       });
     }
     const repoContext = await this.contextService.requireRepoContext({
@@ -28175,7 +28386,7 @@ class ViewPRCommand extends BaseCommand {
       workspace: repoContext.workspace,
       repoSlug: repoContext.repoSlug,
       pullRequestId: prId
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Pull request #${prId} not found in ${repoContext.workspace}/${repoContext.repoSlug}.`));
     const pr = response.data;
     if (context.globalOptions.json) {
       await this.output.json(pr);
@@ -28337,8 +28548,9 @@ class EditPRCommand extends BaseCommand {
       try {
         body = fs7.readFileSync(options.bodyFile, "utf-8");
       } catch (err) {
+        const isNotFound = err instanceof Error && err.code === "ENOENT";
         throw new BBError({
-          code: 9999 /* UNKNOWN */,
+          code: isNotFound ? 5003 /* FILE_NOT_FOUND */ : 9999 /* UNKNOWN */,
           message: `Failed to read file '${options.bodyFile}': ${err instanceof Error ? err.message : "Unknown error"}`,
           cause: err instanceof Error ? err : undefined,
           context: { bodyFile: options.bodyFile }
@@ -28608,10 +28820,6 @@ class CheckoutPRCommand extends BaseCommand {
 }
 
 // src/commands/pr/diff.command.ts
-import { exec } from "child_process";
-import { promisify as promisify7 } from "util";
-var execAsync = promisify7(exec);
-
 class DiffPRCommand extends BaseCommand {
   pullrequestsApi;
   contextService;
@@ -28722,16 +28930,8 @@ class DiffPRCommand extends BaseCommand {
   }
   async openInBrowser(url2) {
     this.output.info(`Opening ${url2} in your browser...`);
-    const platform2 = process.platform;
-    let command;
-    if (platform2 === "darwin") {
-      command = `open "${url2}"`;
-    } else if (platform2 === "win32") {
-      command = `start "" "${url2}"`;
-    } else {
-      command = `xdg-open "${url2}"`;
-    }
-    await execAsync(command);
+    const open2 = (await Promise.resolve().then(() => (init_open(), exports_open))).default;
+    await open2(url2);
   }
   async getWebDiffUrl(workspace, repoSlug, prId) {
     const prResponse = await this.pullrequestsApi.repositoriesWorkspaceRepoSlugPullrequestsPullRequestIdGet({
@@ -28961,11 +29161,11 @@ class ActivityPRCommand extends BaseCommand {
     return activity.type ? activity.type.toLowerCase() : "activity";
   }
   getActorName(activity) {
-    const user = activity.comment?.user ?? activity.comment?.author ?? activity.approval?.user ?? activity.update?.author ?? activity.changes_requested?.user ?? activity.merge?.user ?? activity.decline?.user ?? activity.commit?.author?.user ?? activity.user;
+    const user = activity.comment?.user ?? activity.comment?.author ?? activity.approval?.user ?? activity.changes_requested?.user ?? activity.merge?.user ?? activity.decline?.user ?? activity.commit?.author?.user ?? activity.update?.author ?? activity.user;
     return getUserDisplayName(user) ?? "Unknown";
   }
   formatActivityDate(activity) {
-    const date = activity.comment?.created_on ?? activity.approval?.date ?? activity.update?.date ?? activity.changes_requested?.date ?? activity.merge?.date ?? activity.decline?.date ?? activity.commit?.date;
+    const date = activity.comment?.created_on ?? activity.approval?.date ?? activity.changes_requested?.date ?? activity.merge?.date ?? activity.decline?.date ?? activity.commit?.date ?? activity.update?.date;
     if (!date) {
       return "-";
     }
@@ -29034,16 +29234,23 @@ class CommentPRCommand extends BaseCommand {
     this.contextService = contextService;
   }
   async execute(options, context) {
+    const validModesNote = "Valid modes: (1) general comment (no flags); (2) file-level comment (--file + --line-to or --line-from); (3) inline comment with line range (--file + --line-from + --line-to).";
     if ((options.lineTo || options.lineFrom) && !options.file) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "--file is required when using --line-to or --line-from"
+        message: this.appendHelpHint(`--file is required when using --line-to or --line-from. ${validModesNote}`),
+        context: {
+          validModes: ["general", "file", "inline"]
+        }
       });
     }
     if (options.file && !options.lineTo && !options.lineFrom) {
       throw new BBError({
         code: 5001 /* VALIDATION_REQUIRED */,
-        message: "At least one of --line-to or --line-from is required when using --file"
+        message: this.appendHelpHint(`At least one of --line-to or --line-from is required when using --file. ${validModesNote}`),
+        context: {
+          validModes: ["general", "file", "inline"]
+        }
       });
     }
     if (options.lineTo) {
@@ -29575,13 +29782,13 @@ class ViewSnippetCommand extends BaseCommand {
     const response = await this.snippetsApi.snippetsWorkspaceEncodedIdGet({
       workspace,
       encodedId: options.id
-    });
+    }).catch((error) => rethrowWithNotFoundContext(error, `Snippet ${options.id} not found in workspace ${workspace}.`));
     const snippet = response.data;
     const fileNames = this.extractFileNames(snippet);
     if (options.file !== undefined) {
       if (!fileNames.includes(options.file)) {
         throw new BBError({
-          code: 5002 /* VALIDATION_INVALID */,
+          code: 5003 /* FILE_NOT_FOUND */,
           message: `File not found in snippet: ${options.file}`,
           context: { file: options.file, available: fileNames }
         });
@@ -29689,7 +29896,7 @@ class CreateSnippetCommand extends BaseCommand {
     for (const filePath of options.file) {
       if (!fs8.existsSync(filePath)) {
         throw new BBError({
-          code: 5002 /* VALIDATION_INVALID */,
+          code: 5003 /* FILE_NOT_FOUND */,
           message: `File not found: ${filePath}`,
           context: { file: filePath }
         });
@@ -29748,7 +29955,7 @@ class EditSnippetCommand extends BaseCommand {
       for (const filePath of options.file) {
         if (!fs9.existsSync(filePath)) {
           throw new BBError({
-            code: 5002 /* VALIDATION_INVALID */,
+            code: 5003 /* FILE_NOT_FOUND */,
             message: `File not found: ${filePath}`,
             context: { file: filePath }
           });
@@ -30052,7 +30259,7 @@ class GetConfigCommand extends BaseCommand {
     if (GetConfigCommand.HIDDEN_KEYS.includes(key)) {
       throw new BBError({
         code: 4003 /* CONFIG_INVALID_KEY */,
-        message: `Cannot display '${key}' - use 'bb auth token' to get authentication credentials`,
+        message: `Cannot display '${key}' - it is part of your authentication credentials, not config. ` + `Use 'bb auth token' to retrieve credentials, or run 'bb config list' to see readable keys.`,
         context: { key }
       });
     }
@@ -30164,9 +30371,11 @@ class ListConfigCommand extends BaseCommand {
     ]);
     if (rows.length === 0) {
       this.output.text("No configuration set");
-      return;
+    } else {
+      this.output.table(["KEY", "VALUE"], rows);
     }
-    this.output.table(["KEY", "VALUE"], rows);
+    this.output.text("");
+    this.output.text(this.output.dim(`Settable keys: ${SETTABLE_CONFIG_KEYS.join(", ")}. Run 'bb config set --help' for details.`));
   }
 }
 
@@ -30199,7 +30408,7 @@ class InstallCompletionCommand extends BaseCommand {
       this.output.text("Restart your shell or source your profile to enable completions.");
     } catch (error) {
       throw new BBError({
-        code: 9999 /* UNKNOWN */,
+        code: 9001 /* COMPLETION_INSTALL_FAILED */,
         message: `Failed to install completions: ${error}`,
         cause: error instanceof Error ? error : undefined
       });
@@ -30234,7 +30443,7 @@ class UninstallCompletionCommand extends BaseCommand {
       this.output.success("Shell completions uninstalled successfully!");
     } catch (error) {
       throw new BBError({
-        code: 9999 /* UNKNOWN */,
+        code: 9002 /* COMPLETION_UNINSTALL_FAILED */,
         message: `Failed to uninstall completions: ${error}`,
         cause: error instanceof Error ? error : undefined
       });
@@ -30569,6 +30778,15 @@ function createHelpTextBuilder(noColor) {
         sections.push(`  ${c.bold(name.padEnd(maxLen + 2))}${c.dim(desc)}`);
       }
     }
+    if (config.seeAlso?.length) {
+      if (sections.length)
+        sections.push("");
+      sections.push(c.bold("See also:"));
+      const maxLen = Math.max(...config.seeAlso.map((e) => e.label.length));
+      for (const { label, url: url2 } of config.seeAlso) {
+        sections.push(`  ${c.bold(label.padEnd(maxLen + 2))}${c.cyan(url2)}`);
+      }
+    }
     return `
 ` + sections.join(`
 `) + `
@@ -30754,14 +30972,28 @@ function withGlobalOptions(options, context) {
   };
 }
 var cli = new Command;
-cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json [fields]", "Output as JSON; optionally project to a comma-separated field list (e.g. number,title,author.display_name)").option("--jq <expression>", "Filter the JSON output through a jq expression (requires --json)").option("--no-color", "Disable color output").option("-w, --workspace <workspace>", "Specify workspace").option("-r, --repo <repo>", "Specify repository").addHelpText("after", buildHelpText({
+cli.name("bb").description("A command-line interface for Bitbucket Cloud").version(pkg2.version).option("--json [fields]", "Output as JSON; optionally project to a comma-separated field list (e.g. number,title,author.display_name)").option("--jq <expression>", `Filter the JSON output through a jq expression \u2014 runs in-process via embedded jq, requires --json (e.g. '.pullRequests[] | select(.state == "OPEN") | .title')`).option("--no-color", "Disable color output").option("-w, --workspace <workspace>", "Specify workspace").option("-r, --repo <repo>", "Specify repository").addHelpText("after", buildHelpText({
   envVars: {
     BB_USERNAME: "Bitbucket username (fallback for auth login)",
     BB_API_TOKEN: "Bitbucket API token (fallback for auth login)",
     NO_COLOR: "Disable color output when set",
     FORCE_COLOR: "Force color output when set (and not '0')",
     DEBUG: "Enable HTTP debug logging when 'true'"
-  }
+  },
+  seeAlso: [
+    {
+      label: "Quick Start",
+      url: "https://bitbucket-cli.paulvanderlei.com/getting-started/quickstart/"
+    },
+    {
+      label: "Scripting",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/scripting/"
+    },
+    {
+      label: "Changelog",
+      url: "https://bitbucket-cli.paulvanderlei.com/help/changelog/"
+    }
+  ]
 })).action(async () => {
   cli.outputHelp();
   const versionService = container.resolve(ServiceTokens.VersionService);
@@ -30777,9 +31009,23 @@ cli.name("bb").description("A command-line interface for Bitbucket Cloud").versi
       output.text("\u2500".repeat(50));
     }
   } catch {}
+  try {
+    const configService = container.resolve(ServiceTokens.ConfigService);
+    const config = await configService.getConfig();
+    const hasBasicAuth = Boolean(config.username && config.apiToken);
+    const hasOAuth = Boolean(config.oauthAccessToken && config.oauthRefreshToken);
+    if (!hasBasicAuth && !hasOAuth) {
+      output.text("");
+      output.text(`Tip: Run '${output.highlight("bb auth login")}' to get started.`);
+    }
+  } catch {}
 });
 var authCmd = new Command("auth").description("Authenticate with Bitbucket");
-authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API token)").option("-u, --username <username>", "Bitbucket username (implies API token auth)").option("-p, --password <password>", "Bitbucket API token (implies API token auth)").option("--app-password", "Use API token authentication instead of OAuth").option("--client-id <clientId>", "Custom OAuth consumer client ID").option("--client-secret <clientSecret>", "Custom OAuth consumer client secret").addHelpText("after", buildHelpText({
+authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API token)").option("-u, --username <username>", "Bitbucket username (implies API token auth)").option("-p, --password <password>", "Bitbucket API token (implies API token auth)").option("--app-password", "Use API token authentication instead of OAuth").option("--client-id <clientId>", "Custom OAuth consumer client ID").option("--client-secret <clientSecret>", "Custom OAuth consumer client secret").addHelpText("before", `
+Default: OAuth (browser-based, recommended).
+` + `For CI/CD: API token via --app-password or BB_API_TOKEN env var.
+` + `Note: Bitbucket app passwords are deprecated; use OAuth or an API token.
+`).addHelpText("after", buildHelpText({
   examples: [
     "bb auth login",
     "bb auth login --app-password -u myuser -p mytoken",
@@ -30793,7 +31039,9 @@ authCmd.command("login").description("Authenticate with Bitbucket (OAuth or API
 })).action(async (options) => {
   await runCommand(ServiceTokens.LoginCommand, options, cli);
 });
-authCmd.command("logout").description("Log out of Bitbucket").addHelpText("after", buildHelpText({ examples: ["bb auth logout"] })).action(async () => {
+authCmd.command("logout").description("Log out of Bitbucket").addHelpText("after", buildHelpText({
+  examples: ["bb auth logout", "bb auth logout --json"]
+})).action(async () => {
   await runCommand(ServiceTokens.LogoutCommand, undefined, cli);
 });
 authCmd.command("status").description("Show authentication status").addHelpText("after", buildHelpText({
@@ -30901,7 +31149,17 @@ prCmd.command("create").description("Create a pull request").option("-t, --title
     source: "current git branch",
     destination: "main",
     "default-reviewers": "false (override with --default-reviewers or config key prCreateIncludeDefaultReviewers)"
-  }
+  },
+  seeAlso: [
+    {
+      label: "Repository Context",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/repository-context/"
+    },
+    {
+      label: "Default reviewers",
+      url: "https://bitbucket-cli.paulvanderlei.com/commands/repo/#bb-repo-default-reviewers"
+    }
+  ]
 })).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CreatePRCommand, withGlobalOptions(options, context), cli, context);
@@ -30916,7 +31174,17 @@ prCmd.command("list").description("List pull requests").option("-s, --state <sta
   validValues: {
     "Valid states": [...PR_STATES]
   },
-  defaults: { state: "OPEN", limit: "25" }
+  defaults: { state: "OPEN", limit: "25" },
+  seeAlso: [
+    {
+      label: "Scripting & Automation",
+      url: "https://bitbucket-cli.paulvanderlei.com/guides/scripting/"
+    },
+    {
+      label: "JSON Output",
+      url: "https://bitbucket-cli.paulvanderlei.com/reference/json-output/"
+    }
+  ]
 })).action(async (options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListPRsCommand, withGlobalOptions(options, context), cli, context);
@@ -30981,24 +31249,50 @@ prCmd.command("merge <id>").description("Merge a pull request").option("-m, --me
       "rebase_fast_forward",
       "rebase_merge"
     ]
+  },
+  defaults: {
+    strategy: "the repository's configured merge strategy (typically merge_commit)"
   }
 })).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.MergePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("approve <id>").description("Approve a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr approve 42"] })).action(async (id, options) => {
+prCmd.command("approve <id>").description("Approve a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr approve 42",
+    "bb pr approve 42 --json",
+    "bb pr approve 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ApprovePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("decline <id>").description("Decline a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr decline 42"] })).action(async (id, options) => {
+prCmd.command("decline <id>").description("Decline a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr decline 42",
+    "bb pr decline 42 --json",
+    "bb pr decline 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeclinePRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("ready <id>").description("Mark a draft pull request as ready for review").addHelpText("after", buildHelpText({ examples: ["bb pr ready 42"] })).action(async (id, options) => {
+prCmd.command("ready <id>").description("Mark a draft pull request as ready for review").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr ready 42",
+    "bb pr ready 42 --json",
+    "bb pr ready 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.ReadyPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prCmd.command("checkout <id>").description("Checkout a pull request locally").addHelpText("after", buildHelpText({ examples: ["bb pr checkout 42"] })).action(async (id, options) => {
+prCmd.command("checkout <id>").description("Checkout a pull request locally").addHelpText("after", buildHelpText({
+  examples: [
+    "bb pr checkout 42",
+    "bb pr checkout 42 -w my-workspace -r my-repo"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.CheckoutPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
@@ -31040,13 +31334,19 @@ prCommentsCmd.command("add <id> <message>").description("Add a comment to a pull
   await runCommand(ServiceTokens.CommentPRCommand, withGlobalOptions({ id, message, ...options }, context), cli, context);
 });
 prCommentsCmd.command("edit <pr-id> <comment-id> <message>").description("Edit a comment on a pull request").addHelpText("after", buildHelpText({
-  examples: ['bb pr comments edit 42 12345 "Updated comment"']
+  examples: [
+    'bb pr comments edit 42 12345 "Updated comment"',
+    'bb pr comments edit 42 12345 "Updated comment" --json'
+  ]
 })).action(async (prId, commentId, message, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.EditCommentPRCommand, withGlobalOptions({ prId, commentId, message }, context), cli, context);
 });
 prCommentsCmd.command("delete <pr-id> <comment-id>").description("Delete a comment on a pull request").option("-y, --yes", "Skip confirmation prompt").addHelpText("after", buildHelpText({
-  examples: ["bb pr comments delete 42 12345 --yes"]
+  examples: [
+    "bb pr comments delete 42 12345",
+    "bb pr comments delete 42 12345 --yes"
+  ]
 })).action(async (prId, commentId, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteCommentPRCommand, withGlobalOptions({ prId, commentId, ...options }, context), cli, context);
@@ -31058,11 +31358,21 @@ prReviewersCmd.command("list <id>").description("List reviewers on a pull reques
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListReviewersPRCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-prReviewersCmd.command("add <id> <username>").description("Add a reviewer to a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr reviewers add 42 jdoe"] })).action(async (id, username, options) => {
+prReviewersCmd.command("add <id> <username>").description("Add a reviewer to a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr reviewers add 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"',
+    'bb pr reviewers add 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"'
+  ]
+})).action(async (id, username, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.AddReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
 });
-prReviewersCmd.command("remove <id> <username>").description("Remove a reviewer from a pull request").addHelpText("after", buildHelpText({ examples: ["bb pr reviewers remove 42 jdoe"] })).action(async (id, username, options) => {
+prReviewersCmd.command("remove <id> <username>").description("Remove a reviewer from a pull request").addHelpText("after", buildHelpText({
+  examples: [
+    'bb pr reviewers remove 42 "712020:3cfed7e0-0ed6-49fc-bb35-410a00ccee6f"',
+    'bb pr reviewers remove 42 "{c1cb1bb5-2e32-456e-a373-43978dc12aa1}"'
+  ]
+})).action(async (id, username, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.RemoveReviewerPRCommand, withGlobalOptions({ id, username, ...options }, context), cli, context);
 });
@@ -31121,11 +31431,18 @@ snippetCmd.command("delete <id>").description("Delete a snippet").option("-y, --
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCmd.command("watch <id>").description("Watch a snippet").addHelpText("after", buildHelpText({ examples: ["bb snippet watch kypj"] })).action(async (id, options) => {
+snippetCmd.command("watch <id>").description("Watch a snippet").addHelpText("after", buildHelpText({
+  examples: ["bb snippet watch kypj", "bb snippet watch kypj -w my-team"]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.WatchSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCmd.command("unwatch <id>").description("Stop watching a snippet").addHelpText("after", buildHelpText({ examples: ["bb snippet unwatch kypj"] })).action(async (id, options) => {
+snippetCmd.command("unwatch <id>").description("Stop watching a snippet").addHelpText("after", buildHelpText({
+  examples: [
+    "bb snippet unwatch kypj",
+    "bb snippet unwatch kypj -w my-team"
+  ]
+})).action(async (id, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.UnwatchSnippetCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
@@ -31140,20 +31457,31 @@ snippetCommentsCmd.command("list <id>").description("List comments on a snippet"
   const context = createContext(cli);
   await runCommand(ServiceTokens.ListSnippetCommentsCommand, withGlobalOptions({ id, ...options }, context), cli, context);
 });
-snippetCommentsCmd.command("add <id>").description("Add a comment to a snippet").option("-m, --message <text>", "Comment message").addHelpText("after", buildHelpText({
-  examples: ['bb snippet comments add kypj -m "Great snippet!"']
-})).action(async (id, options) => {
+snippetCommentsCmd.command("add <id> [message]").description("Add a comment to a snippet (message is required)").option("-m, --message <text>", "Comment message (alternative to the positional [message] argument; one of the two is required)").addHelpText("after", buildHelpText({
+  examples: [
+    'bb snippet comments add kypj "Great snippet!"',
+    'bb snippet comments add kypj -m "Great snippet!"',
+    'bb snippet comments add kypj "Great snippet!" --json'
+  ]
+})).action(async (id, message, options) => {
   const context = createContext(cli);
-  await runCommand(ServiceTokens.AddSnippetCommentCommand, withGlobalOptions({ id, ...options }, context), cli, context);
+  const resolvedMessage = message ?? options.message;
+  await runCommand(ServiceTokens.AddSnippetCommentCommand, withGlobalOptions({ id, ...options, message: resolvedMessage }, context), cli, context);
 });
 snippetCommentsCmd.command("edit <snippet-id> <comment-id> <message>").description("Edit a comment on a snippet").addHelpText("after", buildHelpText({
-  examples: ['bb snippet comments edit kypj 123 "Updated comment"']
+  examples: [
+    'bb snippet comments edit kypj 123 "Updated comment"',
+    'bb snippet comments edit kypj 123 "Updated comment" --json'
+  ]
 })).action(async (snippetId, commentId, message, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.EditSnippetCommentCommand, withGlobalOptions({ snippetId, commentId, message }, context), cli, context);
 });
 snippetCommentsCmd.command("delete <snippet-id> <comment-id>").description("Delete a comment on a snippet").option("-y, --yes", "Skip confirmation prompt").addHelpText("after", buildHelpText({
-  examples: ["bb snippet comments delete kypj 123 --yes"]
+  examples: [
+    "bb snippet comments delete kypj 123",
+    "bb snippet comments delete kypj 123 --yes"
+  ]
 })).action(async (snippetId, commentId, options) => {
   const context = createContext(cli);
   await runCommand(ServiceTokens.DeleteSnippetCommentCommand, withGlobalOptions({ snippetId, commentId, ...options }, context), cli, context);
@@ -31168,7 +31496,8 @@ configCmd.command("get <key>").description("Get a configuration value").addHelpT
       "username",
       "defaultWorkspace",
       "skipVersionCheck",
-      "versionCheckInterval"
+      "versionCheckInterval",
+      "prCreateIncludeDefaultReviewers"
     ]
   }
 })).action(async (key) => {
@@ -31184,9 +31513,16 @@ configCmd.command("set <key> <value>").description("Set a configuration value").
     "Settable config keys": [
       "defaultWorkspace (string)",
       "skipVersionCheck (true/false)",
-      "versionCheckInterval (positive integer, seconds)"
+      "versionCheckInterval (positive integer, seconds)",
+      "prCreateIncludeDefaultReviewers (true/false)"
     ]
-  }
+  },
+  seeAlso: [
+    {
+      label: "Configuration File",
+      url: "https://bitbucket-cli.paulvanderlei.com/reference/configuration/"
+    }
+  ]
 })).action(async (key, value) => {
   await runCommand(ServiceTokens.SetConfigCommand, { key, value }, cli);
 });
@@ -31197,10 +31533,20 @@ configCmd.command("list").description("List all configuration values").addHelpTe
 });
 cli.addCommand(configCmd);
 var completionCmd = new Command("completion").description("Shell completion utilities");
-completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").addHelpText("after", buildHelpText({ examples: ["bb completion install"] })).action(async () => {
+completionCmd.command("install").description("Install shell completions for bash, zsh, or fish").addHelpText("after", buildHelpText({
+  examples: ["bb completion install", "bb completion install --json"],
+  validValues: {
+    "Supported shells": ["bash", "zsh", "fish"]
+  }
+})).action(async () => {
   await runCommand(ServiceTokens.InstallCompletionCommand, undefined, cli);
 });
-completionCmd.command("uninstall").description("Uninstall shell completions").addHelpText("after", buildHelpText({ examples: ["bb completion uninstall"] })).action(async () => {
+completionCmd.command("uninstall").description("Uninstall shell completions").addHelpText("after", buildHelpText({
+  examples: ["bb completion uninstall", "bb completion uninstall --json"],
+  validValues: {
+    "Supported shells": ["bash", "zsh", "fish"]
+  }
+})).action(async () => {
   await runCommand(ServiceTokens.UninstallCompletionCommand, undefined, cli);
 });
 cli.addCommand(completionCmd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilatos/bitbucket-cli",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "A command-line interface for Bitbucket Cloud",
   "author": "",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "build": "bun build src/index.ts --outdir dist --target bun --external tabtab",
     "test": "bun test",
     "lint": "tsc --noEmit",
+    "lint:docs": "bun scripts/check-error-codes-docs.ts && bun scripts/check-env-vars-docs.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "generate:api": "openapi-generator-cli generate && bun scripts/patch-generated.ts",