chore: release v1.0.4 (#253)

Update CHANGELOG.md and bump version to 1.0.4.

Change-Id: Ia0d65f4abf271dcff5563aac5ae81bcf4c4c6aea

.codecov.yml

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        target: 60%

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+<!-- Briefly describe the motivation and scope of this change in 1-3 sentences. -->
+
+## Changes
+<!-- List the main changes in this PR. -->
+- Change 1
+- Change 2
+
+## Test Plan
+<!-- Describe how this change was verified. -->
+- [ ] Unit tests pass
+- [ ] Manual local verification confirms the `lark xxx` command works as expected
+
+## Related Issues
+<!-- Link related issues. Use Closes/Fixes to close them automatically. -->
+- None

.github/workflows/cli-e2e.yml

@@ -0,0 +1,135 @@
+name: CLI E2E Tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - Makefile
+      - scripts/fetch_meta.py
+      - tests/cli_e2e/**
+      - .github/workflows/cli-e2e.yml
+  pull_request:
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - Makefile
+      - scripts/fetch_meta.py
+      - tests/cli_e2e/**
+      - .github/workflows/cli-e2e.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  cli-e2e:
+    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    env:
+      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
+      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+
+      - name: Build lark-cli
+        run: make build
+
+      - name: Configure bot credentials
+        run: |
+          if [ -z "$TEST_BOT1_APP_ID" ] || [ -z "$TEST_BOT1_APP_SECRET" ]; then
+            echo "::error::Missing required secrets: TEST_BOT1_APP_ID / TEST_BOT1_APP_SECRET"
+            exit 1
+          fi
+          printf '%s\n' "$TEST_BOT1_APP_SECRET" | ./lark-cli config init --app-id "$TEST_BOT1_APP_ID" --app-secret-stdin
+
+      - name: Run CLI E2E tests
+        env:
+          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+        run: |
+          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
+          if [ -z "$packages" ]; then
+            echo "No CLI E2E packages to test after exclusions."
+            exit 1
+          fi
+          go run gotest.tools/gotestsum@v1.12.3 --format testname --junitfile cli-e2e-report.xml -- -count=1 -v $packages
+
+      - name: Summarize CLI E2E test report
+        if: ${{ !cancelled() }}
+        run: |
+          python3 - <<'PY'
+          import os
+          import xml.etree.ElementTree as ET
+
+          report_path = "cli-e2e-report.xml"
+          summary_path = os.environ["GITHUB_STEP_SUMMARY"]
+
+          root = ET.parse(report_path).getroot()
+          suites = [root] if root.tag == "testsuite" else root.findall("testsuite")
+
+          tests = failures = errors = skipped = 0
+          failed_cases = []
+          skipped_cases = []
+
+          for suite in suites:
+            tests += int(suite.attrib.get("tests", 0))
+            failures += int(suite.attrib.get("failures", 0))
+            errors += int(suite.attrib.get("errors", 0))
+            skipped += int(suite.attrib.get("skipped", 0))
+
+            for case in suite.findall("testcase"):
+              classname = case.attrib.get("classname", "")
+              name = case.attrib.get("name", "")
+              label = f"{classname}.{name}" if classname else name
+
+              failure = case.find("failure")
+              error = case.find("error")
+              skipped_node = case.find("skipped")
+
+              if failure is not None or error is not None:
+                message = ""
+                node = failure if failure is not None else error
+                if node is not None:
+                  message = node.attrib.get("message", "") or (node.text or "").strip()
+                failed_cases.append((label, message))
+              elif skipped_node is not None:
+                message = skipped_node.attrib.get("message", "") or (skipped_node.text or "").strip()
+                skipped_cases.append((label, message))
+
+          passed = tests - failures - errors - skipped
+
+          with open(summary_path, "a", encoding="utf-8") as f:
+            f.write("## CLI E2E Test Report\n\n")
+            f.write(f"- Total: {tests}\n")
+            f.write(f"- Passed: {passed}\n")
+            f.write(f"- Failed: {failures}\n")
+            f.write(f"- Errors: {errors}\n")
+            f.write(f"- Skipped: {skipped}\n\n")
+
+            if failed_cases:
+              f.write("### Failed Tests\n\n")
+              for label, message in failed_cases:
+                detail = f" - {message}" if message else ""
+                f.write(f"- `{label}`{detail}\n")
+              f.write("\n")
+
+            if skipped_cases:
+              f.write("### Skipped Tests\n\n")
+              for label, message in skipped_cases:
+                detail = f" - {message}" if message else ""
+                f.write(f"- `{label}`{detail}\n")
+              f.write("\n")
+          PY

.github/workflows/coverage.yml

@@ -2,22 +2,34 @@ name: Coverage
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - "!tests/cli_e2e/**"
+      - go.mod
+      - go.sum
+      - .github/workflows/coverage.yml
   pull_request:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - "!tests/cli_e2e/**"
+      - go.mod
+      - go.sum
+      - .github/workflows/coverage.yml
 
 permissions:
   contents: read
 
 jobs:
-  codecov:
-    runs-on: ubuntu-22.04
+  coverage:
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
         with:
-          go-version: '1.23'
+          go-version-file: go.mod
 
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
@@ -27,10 +39,20 @@ jobs:
         run: python3 scripts/fetch_meta.py
 
       - name: Run tests with coverage
-        run: go test -coverprofile=coverage.txt -covermode=atomic ./...
+        run: |
+          packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '^github.com/larksuite/cli/tests/cli_e2e/')
+          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
 
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
-        with:
-          files: coverage.txt
-          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Generate coverage report
+        run: |
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
+          echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY

.github/workflows/gitleaks.yml

@@ -0,0 +1,28 @@
+name: Gitleaks
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
+        env:
+          # GITHUB_TOKEN is provided automatically by GitHub Actions.
+          # GITLEAKS_KEY must be configured as a repository secret.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_KEY }}

.github/workflows/lint.yml

@@ -2,43 +2,36 @@ name: Lint
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - .golangci.yml
+      - .github/workflows/lint.yml
   pull_request:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - .golangci.yml
+      - .github/workflows/lint.yml
 
 permissions:
   contents: read
 
 jobs:
-  staticcheck:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version: '1.23'
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta_data.json
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run staticcheck
-        uses: dominikh/staticcheck-action@9716614d4101e79b4340dd97b10e54d68234e431 # v1
-        with:
-          install-go: false
-
   golangci-lint:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
         with:
-          go-version: '1.23'
+          go-version-file: go.mod
 
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
@@ -47,26 +40,21 @@ jobs:
       - name: Fetch meta_data.json
         run: python3 scripts/fetch_meta.py
 
+      - name: Ensure go.mod and go.sum are tidy
+        run: |
+          go mod tidy
+          if ! git diff --quiet go.mod go.sum; then
+            echo "::error::go.mod or go.sum is not tidy. Run 'go mod tidy' and commit the changes."
+            git diff go.mod go.sum
+            exit 1
+          fi
+
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@55c2c1448f86e01eaae002a5a3a9624417608d84 # v6
-        with:
-          version: latest
+        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
 
-  vet:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: Run govulncheck
+        continue-on-error: true # informational until Go version is upgraded
+        run: go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
 
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version: '1.23'
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta_data.json
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run go vet
-        run: go vet ./...
+      - name: Check dependency licenses
+        run: go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown

.github/workflows/pkg-pr-new-comment.yml

@@ -0,0 +1,149 @@
+name: PR Preview Package Comment
+
+on:
+  workflow_run:
+    workflows: ["PR Preview Package"]
+    types: [completed]
+
+permissions:
+  actions: read
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check comment payload artifact
+        id: payload
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const runId = context.payload.workflow_run?.id;
+            const { data } = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: runId,
+              per_page: 100,
+            });
+            const found = Boolean(
+              data.artifacts?.some((artifact) => artifact.name === "pkg-pr-new-comment-payload")
+            );
+            core.setOutput("found", found ? "true" : "false");
+            if (!found) {
+              core.notice("No comment payload artifact found for this run; skipping comment.");
+            }
+
+      - name: Download comment payload
+        if: steps.payload.outputs.found == 'true'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: pkg-pr-new-comment-payload
+          repository: ${{ github.repository }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Comment install command
+        if: steps.payload.outputs.found == 'true'
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const fs = require("fs");
+            const payload = JSON.parse(fs.readFileSync("pkg-pr-new-comment-payload.json", "utf8"));
+            const url = payload?.url;
+            const payloadPr = payload?.pr;
+            const sourceRepo = payload?.sourceRepo;
+            const sourceBranch = payload?.sourceBranch;
+            if (!Number.isInteger(payloadPr)) {
+              throw new Error(`Invalid PR number in artifact payload: ${payloadPr}`);
+            }
+            if (payloadPr <= 0) {
+              throw new Error(`Invalid PR number in artifact payload: ${payloadPr}`);
+            }
+            const issueNumber = payloadPr;
+            const runPrNumber = context.payload.workflow_run?.pull_requests?.[0]?.number;
+            if (Number.isInteger(runPrNumber) && runPrNumber !== issueNumber) {
+              throw new Error(
+                `PR number mismatch between workflow_run (${runPrNumber}) and artifact payload (${issueNumber})`,
+              );
+            }
+
+            if (typeof url !== "string" || url.trim() !== url || /[\u0000-\u001F\u007F]/.test(url)) {
+              throw new Error(`Invalid package URL in payload: ${url}`);
+            }
+            let parsedUrl;
+            try {
+              parsedUrl = new URL(url);
+            } catch {
+              throw new Error(`Invalid package URL in payload: ${url}`);
+            }
+            if (parsedUrl.protocol !== "https:" || parsedUrl.hostname !== "pkg.pr.new") {
+              throw new Error(`Invalid package URL in payload: ${url}`);
+            }
+
+            const safeRepoPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+            const safeBranchPattern = /^[A-Za-z0-9._\/-]+$/;
+            const hasSkillSource =
+              typeof sourceRepo === "string" &&
+              typeof sourceBranch === "string" &&
+              safeRepoPattern.test(sourceRepo) &&
+              safeBranchPattern.test(sourceBranch);
+            const skillSection = hasSkillSource
+              ? [
+                  "",
+                  "### 🧩 Skill update",
+                  "",
+                  "```bash",
+                  `npx skills add ${sourceRepo}#${sourceBranch} -y -g`,
+                  "```",
+                ]
+              : [
+                  "",
+                  "### 🧩 Skill update",
+                  "",
+                  "_Unavailable for this PR because source repo/branch metadata is missing._",
+                ];
+
+            const body = [
+              "<!-- pkg-pr-new-install-guide -->",
+              "## 🚀 PR Preview Install Guide",
+              "",
+              "### 🧰 CLI update",
+              "",
+              "```bash",
+              `npm i -g ${url}`,
+              "```",
+              ...skillSection,
+            ].join("\n");
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              per_page: 100,
+            });
+
+            const existing = comments.find((comment) =>
+              comment.user?.login === "github-actions[bot]" &&
+              typeof comment.body === "string" &&
+              comment.body.includes("<!-- pkg-pr-new-install-guide -->")
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                body,
+              });
+            }

.github/workflows/pkg-pr-new.yml

@@ -0,0 +1,71 @@
+name: PR Preview Package
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go.mod
+
+      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4
+        with:
+          node-version: lts/*
+
+      - name: Build preview package
+        run: ./scripts/build-pkg-pr-new.sh
+
+      - name: Publish to pkg.pr.new
+        run: npx pkg-pr-new publish --no-compact --json output.json --comment=off ./.pkg-pr-new
+
+      - name: Build comment payload
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          SOURCE_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          SOURCE_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          node <<'NODE'
+          const fs = require("fs");
+
+          const output = JSON.parse(fs.readFileSync("output.json", "utf8"));
+          const url = output?.packages?.[0]?.url;
+          if (!url) throw new Error("No package URL found in output.json");
+          if (!url.startsWith("https://pkg.pr.new/")) {
+            throw new Error(`Unexpected package URL: ${url}`);
+          }
+
+          const pr = Number(process.env.PR_NUMBER);
+          if (!Number.isInteger(pr) || pr <= 0) {
+            throw new Error(`Invalid PR_NUMBER: ${process.env.PR_NUMBER}`);
+          }
+
+          const payload = {
+            pr,
+            url,
+            sourceRepo: process.env.SOURCE_REPO || "",
+            sourceBranch: process.env.SOURCE_BRANCH || "",
+          };
+
+          fs.writeFileSync(
+            "pkg-pr-new-comment-payload.json",
+            JSON.stringify(payload),
+          );
+          NODE
+
+      - name: Upload comment payload
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: pkg-pr-new-comment-payload
+          path: pkg-pr-new-comment-payload.json

.github/workflows/pr-labels-test.yml

@@ -0,0 +1,31 @@
+name: Test PR Label Logic
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "scripts/pr-labels/**"
+      - ".github/workflows/pr-labels-test.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "scripts/pr-labels/**"
+      - ".github/workflows/pr-labels-test.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  test-pr-labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run PR label regression tests
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/pr-labels/test.js

.github/workflows/pr-labels.yml

@@ -0,0 +1,43 @@
+name: PR Labels
+
+on:
+  pull_request_target:
+    # NOTE: This event runs with base-branch code and write permissions.
+    # Do NOT add `ref: github.event.pull_request.head.sha` to the checkout step,
+    # as that would execute untrusted PR code with elevated access.
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  sync-pr-labels:
+    if: ${{ github.event.pull_request.state == 'open' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Sync managed PR labels
+        id: sync_pr_labels
+        # Labeling is best-effort and must not block PR merges.
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/pr-labels/index.js
+
+      - name: Warn when label sync fails
+        if: ${{ always() && steps.sync_pr_labels.outcome == 'failure' }}
+        run: |
+          echo "::warning::PR label sync failed; labels may be stale."
+          echo "⚠️ PR label sync failed; labels may be stale." >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release.yml

@@ -33,3 +33,19 @@ jobs:
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-npm:
+    needs: goreleaser
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

.github/workflows/skill-format-check.yml

@@ -0,0 +1,32 @@
+name: Skill Format Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "skills/**"
+      - "scripts/skill-format-check/**"
+      - ".github/workflows/skill-format-check.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "skills/**"
+      - "scripts/skill-format-check/**"
+      - ".github/workflows/skill-format-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Skill Format Check
+        run: node scripts/skill-format-check/index.js

.github/workflows/tests.yml

@@ -2,22 +2,32 @@ name: Tests
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - .github/workflows/tests.yml
   pull_request:
-    branches: [ main ]
+    branches: [main]
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - .github/workflows/tests.yml
 
 permissions:
   contents: read
 
 jobs:
   unit-test:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
         with:
-          go-version: '1.23'
+          go-version-file: go.mod
 
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
@@ -27,4 +37,7 @@ jobs:
         run: python3 scripts/fetch_meta.py
 
       - name: Run tests
-        run: go test -v -race -count=1 -timeout=30s ./cmd/... ./internal/... ./shortcuts/...
+        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
+
+      - name: Build
+        run: go build -v ./...

.gitignore

@@ -30,3 +30,7 @@ test_scripts/
 tests/mail/reports/
 
 /log/
+
+# Generated / test artifacts
+internal/registry/meta_data.json
+cmd/api/download.bin

.gitleaks.toml

@@ -0,0 +1,16 @@
+title = "lark-cli gitleaks config"
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "lark-bot-app-id"
+description = "Detect Lark bot app ids"
+regex = '''\bcli_[a-z0-9]{16}\b'''
+keywords = ["cli_"]
+
+[[rules]]
+id = "lark-session-token"
+description = "Detect Lark session tokens"
+regex = '''\bXN0YXJ0-[A-Za-z0-9_-]+-WVuZA\b'''
+keywords = ["XN0YXJ0-", "-WVuZA"]

.golangci.yml

@@ -0,0 +1,66 @@
+version: "2"
+
+run:
+  timeout: 5m
+
+linters:
+  default: none
+  enable:
+    - asasalint       # checks for pass []any as any in variadic func(...any)
+    - asciicheck      # checks that code does not contain non-ASCII identifiers
+    - bidichk         # checks for dangerous unicode character sequences
+    - bodyclose       # checks whether HTTP response body is closed successfully
+    - copyloopvar     # detects places where loop variables are copied
+    - durationcheck   # checks for two durations multiplied together
+    - exptostd        # detects functions from golang.org/x/exp/ replaceable by std
+    - fatcontext      # detects nested contexts in loops
+    - gocheckcompilerdirectives # validates go compiler directive comments (//go:)
+    - gochecksumtype  # checks exhaustiveness on Go "sum types"
+    - gocritic        # diagnostics for bugs, performance and style
+    - gomoddirectives # checks for replace, retract, and exclude in go.mod
+    - goprintffuncname # checks that printf-like functions end with f
+    - govet           # reports suspicious constructs
+    - ineffassign     # detects ineffective assignments
+    - nilerr          # finds code that returns nil even if error is not nil
+    - nolintlint      # reports ill-formed nolint directives
+    - nosprintfhostport # checks for misuse of Sprintf to construct host:port
+    - reassign        # checks that package variables are not reassigned
+    - unconvert       # removes unnecessary type conversions
+    - unused          # checks for unused constants, variables, functions and types
+
+    # To enable later after fixing existing issues:
+    # - errcheck      # checks for unchecked errors
+    # - errname       # checks that error types are named XxxError
+    # - errorlint     # checks error wrapping best practices
+    # - gosec         # security-oriented linter
+    # - misspell      # finds commonly misspelled English words
+    # - staticcheck   # comprehensive static analysis
+
+  exclusions:
+    paths:
+      - generated
+    rules:
+      - path: _test\.go$
+        linters:
+          - bodyclose
+          - gocritic
+
+  settings:
+    gocritic:
+      disabled-checks:
+        - appendAssign
+        - hugeParam
+      disabled-tags:
+        - style
+    govet:
+      enable:
+        - httpresponse
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md
+Concise maintainer/developer guide for building, testing, and opening high-quality PRs in this repo.
+
+## Goal (pick one per PR)
+- Make CLI better: improve UX, error messages, help text, flags, and output clarity.
+- Improve reliability: fix bugs, edge cases, and regressions with tests.
+- Improve developer velocity: simplify code paths, reduce complexity, keep behavior explicit.
+- Improve quality gates: strengthen tests/lint/checks without adding heavy process.
+
+## Fast Dev Loop
+1. `make build` (runs `python3 scripts/fetch_meta.py` first)
+2. `make unit-test` (required before PR)
+3. Run changed command(s) manually via `./lark-cli ...`
+
+## Pre-PR Checks (match CI gates)
+1. `make unit-test`
+2. `go mod tidy` (must not change `go.mod`/`go.sum`)
+3. `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main`
+4. If dependencies changed: `go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown`
+5. Optional full local suite: `make test` (vet + unit + integration)
+
+## Test/Check Commands
+- Unit: `make unit-test`
+- Integration: `make integration-test`
+- Full: `make test`
+- Vet only: `make vet`
+- Coverage (local): `go test -race -coverprofile=coverage.txt -covermode=atomic ./...`
+
+## Commit/PR Rules
+- Use Conventional Commits in English: `feat: ...`, `fix: ...`, `docs: ...`, `ci: ...`, `test: ...`, `chore: ...`, `refactor: ...`
+- Keep PR title in the same Conventional Commit format (squash merge keeps it).
+- Before opening a real PR, draft/fill description from `.github/pull_request_template.md` and ensure Summary/Changes/Test Plan are complete.
+- Never commit secrets/tokens/internal sensitive data.

CHANGELOG.md

@@ -2,6 +2,113 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.4] - 2026-04-03
+
+### Features
+
+- Support user identity for im `+chat-create` (#242)
+- Implement authentication response logging (#235)
+- Support im chat member delete and add scope notes (#229)
+
+### Bug Fixes
+
+- **security**: Replace `http.DefaultTransport` with proxy-aware base transport to mitigate MITM risk (#247)
+- **calendar**: Block auto bot fallback without user login (#245)
+
+### Documentation
+
+- **mail**: Add identity guidance to prefer user over bot (#157)
+
+### Refactor
+
+- **dashboard**: Restructure docs for AI-friendly navigation (#191)
+
+### CI
+
+- Add a CLI E2E testing framework for lark-cli, task domain testcase and ci action (#236)
+
+## [v1.0.3] - 2026-04-02
+
+### Features
+
+- Add `--jq` flag for filtering JSON output (#211)
+- Add `+download` shortcut for minutes media download (#101)
+- Add drive import, export, move, and task result shortcuts (#194)
+- Support im message send/reply with uat (#180)
+- Add approve domain (#217)
+
+### Bug Fixes
+
+- **mail**: Use in-memory keyring in mail scope tests to avoid macOS keychain popups (#212)
+- **mail**: On-demand scope checks and watch event filtering (#198)
+- Use curl for binary download to support proxy and add npmmirror fallback (#226)
+- Normalize escaped sheet range separators (#207)
+
+### Documentation
+
+- **mail**: Clarify JSON output is directly usable without extra encoding (#228)
+- Clarify docs search query usage (#221)
+
+### CI
+
+- Add gitleaks scanning workflow and custom rules (#142)
+
+## [v1.0.2] - 2026-04-01
+
+### Features
+
+- Improve OS keychain/DPAPI access error handling for sandbox environments (#173)
+- **mail**: Auto-resolve local image paths in draft body HTML (#139)
+
+### Bug Fixes
+
+- Correct URL formatting in login `--no-wait` output (#169)
+
+### Documentation
+
+- Add concise AGENTS development guide (#178)
+
+### CI
+
+- Refine PR business area labels and introduce skill format check (#148)
+
+### Chore
+
+- Add pull request template (#176)
+
+## [v1.0.1] - 2026-03-31
+
+### Features
+
+- Add automatic CLI update detection and notification (#144)
+- Add npm publish job to release workflow (#145)
+- Support auto extension for downloads (#16)
+- Remove useless files (#131)
+- Normalize markdown message send/reply output (#28)
+- Add auto-pagination to messages search and update lark-im docs (#30)
+
+### Bug Fixes
+
+- **base**: Use base history read scope for record history list (#96)
+- Remove sensitive send scope from reply and forward shortcuts (#92)
+- Resolve silent failure in `lark-cli api` error output (#85)
+
+### Documentation
+
+- **base**: Clarify field description usage in json (#90)
+- Update Base description to include all capabilities (#61)
+- Add official badge to distinguish from third-party Lark CLI tools (#103)
+- Rename user-facing Bitable references to Base (#11)
+- Add star history chart to readmes (#12)
+- Simplify installation steps by merging CLI and Skills into one section (#26)
+- Add npm version badge and improve AI agent tip wording (#23)
+- Emphasize Skills installation as required for AI Agents (#19)
+- Clarify install methods as alternatives and add source build steps
+
+### CI
+
+- Improve CI workflows and add golangci-lint config (#71)
+
 ## [v1.0.0] - 2026-03-28
 
 ### Initial Release
@@ -27,7 +134,7 @@ Built-in shortcuts for commonly used Lark APIs, enabling concise commands like `
 - **Drive** — Upload, download, and manage cloud documents.
 - **Docs** — Work with Lark documents.
 - **Sheets** — Interact with spreadsheets.
-- **Base (Bitable)** — Manage multi-dimensional tables.
+- **Base** — Manage multi-dimensional tables.
 - **Calendar** — Create and manage calendar events.
 - **Mail** — Send and manage emails.
 - **Contact** — Look up users and departments.
@@ -54,4 +161,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.4]: https://github.com/larksuite/cli/releases/tag/v1.0.4
+[v1.0.3]: https://github.com/larksuite/cli/releases/tag/v1.0.3
+[v1.0.2]: https://github.com/larksuite/cli/releases/tag/v1.0.2
+[v1.0.1]: https://github.com/larksuite/cli/releases/tag/v1.0.1
 [v1.0.0]: https://github.com/larksuite/cli/releases/tag/v1.0.0

CLA.md

@@ -1,28 +0,0 @@
-> Thank you for your interest in open source projects hosted or managed by ByteDance Ltd. and/or its Affiliates ("**ByteDance**") . In order to clarify the intellectual property license granted with Contributions from any person or entity, ByteDance must have a Contributor License Agreement ("**CLA**") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of ByteDance and its users; it does not change your rights to use your own Contributions for any other purpose.
-> If you are an individual making a submission on your own behalf, you should accept the Individual Contributor License Agreement. If you are making a submission on behalf of a legal entity (the “**Corporation**”), you should sign the separation Corporate Contributor License Agreement.
-  
-**ByteDance Individual Contributor License Agreement v1.** **1**
-By clicking “Accept” on this page, You accept and agree to the following terms and conditions for Your present and future Contributions submitted to ByteDance. Except for the license granted herein to ByteDance and recipients of software distributed by ByteDance, You reserve all right, title, and interest in and to Your Contributions.
-1.Definitions.
-"Affiliate" shall mean an entity that Controls, is Controlled by, or is under common Control with You or ByteDance, respectively (but only as long as such Control exists).
-"Control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
-"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to ByteDance for inclusion in, or documentation of, any of the products owned or managed by ByteDance (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to ByteDance or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, ByteDance for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution."
-"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with ByteDance. For the avoidance of doubt, the Corporation making a Contribution and all of its Affiliates are considered to be a single Contributor and this CLA shall apply to Contributions Submitted by the Corporation or any of its Affiliates.
-2.Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to ByteDance and to recipients of software distributed by ByteDance a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works.
-3.Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to ByteDance and to recipients of software distributed by ByteDance a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed.
-4.You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to ByteDance, or that your employer has executed a separate Corporate CLA with ByteDance.
-5.You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
-6.You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
-7.Should You wish to submit work that is not Your original creation, You may submit it to ByteDance separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]".
-8.You agree to notify ByteDance of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
-9.You agree that contributions to Projects and information about contributions may be maintained indefinitely and disclosed publicly, including Your name and other information that You submit with your submission.
-10.This Agreement is the entire agreement and understanding between the parties, and supersedes any and all prior agreements, understandings or communications, written or oral, between the parties relating to the subject matter hereof. This Agreement may be assigned by ByteDance.
-  
-[ByteDance Corporate Contributor License Agreement v1.1](./ByteDance_Corporate_Contributor_License_Agreement_v1.1.pdf)
-
-This version of the Contributor License Agreement allows a legal entity (the “Corporation”) to submit Contributions to the applicable project.
-ByteDance Corporate Contributor License Agreement v1.1.pdf
-A person authorized to sign legal documents on behalf of your employer (usually a VP or higher) must sign the Contributor Agreement on behalf of the employer.
-If you have not already signed this agreement, please complete and sign, then scan and email a pdf file of this Agreement to opensource-cla@bytedance.com. Please read this document carefully before signing and keep a copy for your records.
-  
-If you need to update your CLA, please email <opensource-cla@bytedance.com> from the email address associated with your individual or corporate information.

README.md

@@ -2,17 +2,18 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+[![npm version](https://img.shields.io/npm/v/@larksuite/cli.svg)](https://www.npmjs.com/package/@larksuite/cli)
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-A command-line tool for [Lark/Feishu](https://www.larksuite.com/) Open Platform — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 19 AI Agent [Skills](./skills/).
+The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20 AI Agent [Skills](./skills/).
 
 [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
 
 ## Why lark-cli?
 
-- **Agent-Native Design** — 19 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
-- **Wide Coverage** — 11 business domains, 200+ curated commands, 19 AI Agent [Skills](./skills/)
+- **Agent-Native Design** — 20 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
+- **Wide Coverage** — 12 business domains, 200+ curated commands, 20 AI Agent [Skills](./skills/)
 - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
 - **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
 - **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
@@ -21,19 +22,20 @@ A command-line tool for [Lark/Feishu](https://www.larksuite.com/) Open Platform
 
 ## Features
 
-| Category      | Capabilities                                                                        |
-| ------------- | ----------------------------------------------------------------------------------- |
-| 📅 Calendar   | View agenda, create events, invite attendees, check free/busy status, time suggestions |
-| 💬 Messenger  | Send/reply messages, create and manage group chats, view chat history & threads, search messages, download media |
-| 📄 Docs       | Create, read, update, and search documents, read/write media & whiteboards          |
-| 📁 Drive      | Upload and download files, search docs & wiki, manage comments                      |
-| 📊 Base       | Create and manage tables, fields, records, views, dashboards, data aggregation & analytics |
-| 📈 Sheets     | Create, read, write, append, find, and export spreadsheet data                      |
-| ✅ Tasks      | Create, query, update, and complete tasks; manage task lists, subtasks, comments & reminders |
-| 📚 Wiki       | Create and manage knowledge spaces, nodes, and documents                            |
-| 👤 Contact    | Search users by name/email/phone, get user profiles                                 |
-| 📧 Mail       | Browse, search, read emails, send, reply, forward, manage drafts, watch new mail    |
-| 🎥 Meetings   | Search meeting records, query meeting minutes & recordings                          |
+| Category      | Capabilities                                                                                                                      |
+| ------------- |-----------------------------------------------------------------------------------------------------------------------------------|
+| 📅 Calendar   | View agenda, create events, invite attendees, check free/busy status, time suggestions                                            |
+| 💬 Messenger  | Send/reply messages, create and manage group chats, view chat history & threads, search messages, download media                  |
+| 📄 Docs       | Create, read, update, and search documents, read/write media & whiteboards                                                        |
+| 📁 Drive      | Upload and download files, search docs & wiki, manage comments                                                                    |
+| 📊 Base       | Create and manage tables, fields, records, views, dashboards, workflows, forms, roles & permissions, data aggregation & analytics |
+| 📈 Sheets     | Create, read, write, append, find, and export spreadsheet data                                                                    |
+| ✅ Tasks      | Create, query, update, and complete tasks; manage task lists, subtasks, comments & reminders                                      |
+| 📚 Wiki       | Create and manage knowledge spaces, nodes, and documents                                                                          |
+| 👤 Contact    | Search users by name/email/phone, get user profiles                                                                               |
+| 📧 Mail       | Browse, search, read emails, send, reply, forward, manage drafts, watch new mail                                                  |
+| 🎥 Meetings   | Search meeting records, query meeting minutes & recordings                                                                        |
+| ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 
 ## Installation & Quick Start
 
@@ -46,31 +48,32 @@ Before you start, make sure you have:
 
 ### Quick Start (Human Users)
 
-> **Tip:** If you have an AI Agent, you can hand this README to it and let the AI handle installation and setup — jump to [Quick Start (AI Agent)](#quick-start-ai-agent).
+> **Note for AI assistants:** If you are an AI Agent helping the user with installation, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent), which contains all the steps you need to complete.
 
-#### Install CLI
+#### Install
 
-**From npm (recommended):**
+Choose **one** of the following methods:
+
+**Option 1 — From npm (recommended):**
 
 ```bash
+# Install CLI
 npm install -g @larksuite/cli
+
+# Install CLI SKILL (required)
+npx skills add larksuite/cli -y -g
 ```
 
-**From source:**
+**Option 2 — From source:**
+
+Requires Go `v1.23`+ and Python 3.
 
 ```bash
+git clone https://github.com/larksuite/cli.git
+cd cli
 make install
-```
 
-#### Install AI Agent Skills
-
-[Skills](./skills/) are structured instruction documents that enable AI Agents to use this CLI:
-
-```bash
-# Install all skills to current directory
-npx skills add larksuite/cli -y
-
-# Install all skills globally
+# Install CLI SKILL (required)
 npx skills add larksuite/cli -y -g
 ```
 
@@ -91,48 +94,62 @@ lark-cli calendar +agenda
 
 > The following steps are for AI Agents. Some steps require the user to complete actions in a browser.
 
+**Step 1 — Install**
+
 ```bash
-# 1. Install CLI
+# Install CLI
 npm install -g @larksuite/cli
 
-# 2. Install Skills (enables AI Agent to use this CLI)
-npx skills add larksuite/cli --all -y
+# Install CLI SKILL (required)
+npx skills add larksuite/cli -y -g
+```
 
-# 3. Configure app credentials
-# Important: run this command in the background. It will output an authorization URL — extract it and send it to the user. The command exits automatically after the user completes the setup in browser.
+**Step 2 — Configure app credentials**
+
+> Run this command in the background. It will output an authorization URL — extract it and send it to the user. The command exits automatically after the user completes the setup in the browser.
+
+```bash
 lark-cli config init --new
+```
 
-# 4. Login
-# Same as above: run in the background, extract the authorization URL and send it to the user.
+**Step 3 — Login**
+
+> Same as above: run in the background, extract the authorization URL and send it to the user.
+
+```bash
 lark-cli auth login --recommend
+```
 
-# 5. Verify
+**Step 4 — Verify**
+
+```bash
 lark-cli auth status
 ```
 
 ## Agent Skills
 
-| Skill                           | Description                                                                           |
-| ------------------------------- | ------------------------------------------------------------------------------------- |
+| Skill                           | Description                                                                                                    |
+| ------------------------------- |----------------------------------------------------------------------------------------------------------------|
 | `lark-shared`                   | App config, auth login, identity switching, scope management, security rules (auto-loaded by all other skills) |
-| `lark-calendar`                 | Calendar events, agenda view, free/busy queries, time suggestions                     |
-| `lark-im`                       | Send/reply messages, group chat management, message search, upload/download images & files, reactions |
-| `lark-doc`                      | Create, read, update, search documents (Markdown-based)                               |
-| `lark-drive`                    | Upload, download files, manage permissions & comments                                 |
-| `lark-sheets`                   | Create, read, write, append, find, export spreadsheets                                |
-| `lark-base`                     | Tables, fields, records, views, dashboards, data aggregation & analytics              |
-| `lark-task`                     | Tasks, task lists, subtasks, reminders, member assignment                              |
-| `lark-mail`                     | Browse, search, read emails, send, reply, forward, draft management, watch new mail   |
-| `lark-contact`                  | Search users by name/email/phone, get user profiles                                   |
-| `lark-wiki`                     | Knowledge spaces, nodes, documents                                                    |
-| `lark-event`                    | Real-time event subscriptions (WebSocket), regex routing & agent-friendly format       |
-| `lark-vc`                       | Search meeting records, query meeting minutes (summary, todos, transcript)             |
-| `lark-whiteboard`               | Whiteboard/chart DSL rendering                                                        |
-| `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters)                            |
-| `lark-openapi-explorer`         | Explore underlying APIs from official docs                                            |
-| `lark-skill-maker`              | Custom skill creation framework                                                       |
-| `lark-workflow-meeting-summary` | Workflow: meeting minutes aggregation & structured report                              |
-| `lark-workflow-standup-report`  | Workflow: agenda & todo summary                                                       |
+| `lark-calendar`                 | Calendar events, agenda view, free/busy queries, time suggestions                                              |
+| `lark-im`                       | Send/reply messages, group chat management, message search, upload/download images & files, reactions          |
+| `lark-doc`                      | Create, read, update, search documents (Markdown-based)                                                        |
+| `lark-drive`                    | Upload, download files, manage permissions & comments                                                          |
+| `lark-sheets`                   | Create, read, write, append, find, export spreadsheets                                                         |
+| `lark-base`                     | Tables, fields, records, views, dashboards, data aggregation & analytics                                       |
+| `lark-task`                     | Tasks, task lists, subtasks, reminders, member assignment                                                      |
+| `lark-mail`                     | Browse, search, read emails, send, reply, forward, draft management, watch new mail                            |
+| `lark-contact`                  | Search users by name/email/phone, get user profiles                                                            |
+| `lark-wiki`                     | Knowledge spaces, nodes, documents                                                                             |
+| `lark-event`                    | Real-time event subscriptions (WebSocket), regex routing & agent-friendly format                               |
+| `lark-vc`                       | Search meeting records, query meeting minutes (summary, todos, transcript)                                     |
+| `lark-whiteboard`               | Whiteboard/chart DSL rendering                                                                                 |
+| `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters)                                                     |
+| `lark-openapi-explorer`         | Explore underlying APIs from official docs                                                                     |
+| `lark-skill-maker`              | Custom skill creation framework                                                                                |
+| `lark-approval`                 | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                   |
+| `lark-workflow-meeting-summary` | Workflow: meeting minutes aggregation & structured report                                                      |
+| `lark-workflow-standup-report`  | Workflow: agenda & todo summary                                                                                |
 
 ## Authentication
 
@@ -250,6 +267,10 @@ We recommend using the Lark/Feishu bot integrated with this tool as a private co
 
 Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/cli&type=Date)](https://star-history.com/#larksuite/cli&Date)
+
 ## Contributing
 
 Community contributions are welcome! If you find a bug or have feature suggestions, please submit an [Issue](https://github.com/larksuite/cli/issues) or [Pull Request](https://github.com/larksuite/cli/pulls).

README.zh.md

@@ -2,17 +2,18 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+[![npm version](https://img.shields.io/npm/v/@larksuite/cli.svg)](https://www.npmjs.com/package/@larksuite/cli)
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书/Lark 开放平台命令行工具 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 19 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 20 个 AI Agent [Skills](./skills/)。
 
 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
 
 ## 为什么选 lark-cli？
 
 - **为 Agent 原生设计** — [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
-- **覆盖面广** — 11 大业务域、200+ 精选命令、 19 个 AI Agent [Skills](./skills/)
+- **覆盖面广** — 12 大业务域、200+ 精选命令、 20 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -21,19 +22,20 @@
 
 ## 功能
 
-| 类别        | 能力                                                                      |
-| ------------- | --------------------------------------------------------------------------- |
-| 📅 日历     | 查看日程、创建日程、邀请参会人、查询忙闲状态、时间建议                    |
-| 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件 |
-| 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                            |
-| 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                                |
-| 📊 多维表格 | 创建和管理多维表格、字段、记录、视图、仪表盘，数据聚合分析                |
-| 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                                |
-| ✅ 任务     | 创建、查询、更新和完成任务；管理任务清单、子任务、评论与提醒              |
-| 📚 知识库   | 创建和管理知识空间、节点和文档                                            |
-| 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                                  |
-| 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件          |
-| 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                                          |
+| 类别        | 能力                                         |
+| ------------- |--------------------------------------------|
+| 📅 日历     | 查看日程、创建日程、邀请参会人、查询忙闲状态、时间建议                |
+| 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件      |
+| 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                    |
+| 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                      |
+| 📊 多维表格 | 创建和管理数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限，数据聚合分析 |
+| 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                      |
+| ✅ 任务     | 创建、查询、更新和完成任务；管理任务清单、子任务、评论与提醒             |
+| 📚 知识库   | 创建和管理知识空间、节点和文档                            |
+| 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                      |
+| 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件           |
+| 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                           |
+| ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 
 ## 安装与快速开始
 
@@ -46,31 +48,32 @@
 
 ### 快速开始（人类用户）
 
-> **Tip:** 如果你拥有 AI Agent，可以直接把本 README 丢给它，让 AI 帮你完成安装和配置 — 跳转到[快速开始（AI Agent）](#快速开始ai-agent)查看。
+> **Note for AI assistants:** 如果你是 AI Agent 且正在协助用户执行安装，请直接跳转到[快速开始（AI Agent）](#快速开始ai-agent)执行，那里包含你需要完成的所有步骤。
 
-#### 安装 CLI
+#### 安装
 
-**从 npm 安装（推荐）：**
+以下两种方式**任选其一**：
+
+**方式一 — 从 npm 安装（推荐）：**
 
 ```bash
+# 安装 CLI
 npm install -g @larksuite/cli
+
+# 安装 CLI SKILL（必需）
+npx skills add larksuite/cli -y -g
 ```
 
-**从源码安装：**
+**方式二 — 从源码安装：**
+
+需要 Go `v1.23`+ 和 Python 3。
 
 ```bash
+git clone https://github.com/larksuite/cli.git
+cd cli
 make install
-```
 
-#### 安装 AI Agent Skills
-
-[Skills](./skills/) 是结构化的指令文档，使 AI Agent 能够使用本 CLI：
-
-```bash
-# 安装所有 skills 到当前目录
-npx skills add larksuite/cli -y
-
-# 安装所有 skills 到全局
+# 安装 CLI SKILL（必需）
 npx skills add larksuite/cli -y -g
 ```
 
@@ -91,49 +94,63 @@ lark-cli calendar +agenda
 
 > 以下步骤面向 AI Agent，部分步骤需要用户在浏览器中配合完成。
 
+**第 1 步 — 安装**
+
 ```bash
-# 1. 安装 CLI
+# 安装 CLI
 npm install -g @larksuite/cli
 
-# 2. 安装 Skills（使 AI Agent 能够使用本 CLI）
-npx skills add larksuite/cli --all -y
+# 安装 CLI SKILL（必需）
+npx skills add larksuite/cli -y -g
+```
 
-# 3. 配置应用凭证
-# 重要：在后台运行此命令，命令会输出一个授权链接，提取该链接并发送给用户，用户在浏览器中完成配置后命令会自动退出。
+**第 2 步 — 配置应用凭证**
+
+> 在后台运行此命令，命令会输出一个授权链接，提取该链接并发送给用户，用户在浏览器中完成配置后命令会自动退出。
+
+```bash
 lark-cli config init --new
+```
 
-# 4. 登录
-# 同上，后台运行，提取授权链接发给用户
+**第 3 步 — 登录**
+
+> 同上，后台运行，提取授权链接发给用户。
+
+```bash
 lark-cli auth login --recommend
+```
 
-# 5. 验证
+**第 4 步 — 验证**
+
+```bash
 lark-cli auth status
 ```
 
 
 ## Agent Skills
 
-| Skill                           | 说明                                                                        |
-| --------------------------------- | ----------------------------------------------------------------------------- |
+| Skill                           | 说明                                        |
+| --------------------------------- |-------------------------------------------|
 | `lark-shared`                   | 应用配置、认证登录、身份切换、权限管理、安全规则（所有其他 skill 自动加载） |
-| `lark-calendar`                 | 日历日程、议程查看、忙闲查询、时间建议                                      |
-| `lark-im`                       | 发送/回复消息、群聊管理、消息搜索、上传下载图片与文件、表情回复             |
-| `lark-doc`                      | 创建、读取、更新、搜索文档（基于 Markdown）                                 |
-| `lark-drive`                    | 上传、下载文件，管理权限与评论                                              |
-| `lark-sheets`                   | 创建、读取、写入、追加、查找、导出电子表格                                  |
-| `lark-base`                     | 多维表格、字段、记录、视图、仪表盘、数据聚合分析                            |
-| `lark-task`                     | 任务、任务清单、子任务、提醒、成员分配                                      |
-| `lark-mail`                     | 浏览、搜索、阅读邮件，发送、回复、转发，草稿管理，监听新邮件                |
-| `lark-contact`                  | 按姓名/邮箱/手机号搜索用户，获取用户信息                                    |
-| `lark-wiki`                     | 知识空间、节点、文档                                                        |
-| `lark-event`                    | 实时事件订阅（WebSocket），支持正则路由与 Agent 友好格式                    |
-| `lark-vc`                       | 搜索会议记录、查询会议纪要产物（总结、待办、逐字稿）                        |
-| `lark-whiteboard`               | 画板/图表 DSL 渲染                                                          |
-| `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节）                                    |
-| `lark-openapi-explorer`         | 从官方文档探索底层 API                                                      |
-| `lark-skill-maker`              | 自定义 skill 创建框架                                                       |
-| `lark-workflow-meeting-summary` | 工作流：会议纪要汇总与结构化报告                                            |
-| `lark-workflow-standup-report`  | 工作流：日程待办摘要                                                        |
+| `lark-calendar`                 | 日历日程、议程查看、忙闲查询、时间建议                       |
+| `lark-im`                       | 发送/回复消息、群聊管理、消息搜索、上传下载图片与文件、表情回复          |
+| `lark-doc`                      | 创建、读取、更新、搜索文档（基于 Markdown）                |
+| `lark-drive`                    | 上传、下载文件，管理权限与评论                           |
+| `lark-sheets`                   | 创建、读取、写入、追加、查找、导出电子表格                     |
+| `lark-base`                     | 多维表格、字段、记录、视图、仪表盘、数据聚合分析                  |
+| `lark-task`                     | 任务、任务清单、子任务、提醒、成员分配                       |
+| `lark-mail`                     | 浏览、搜索、阅读邮件，发送、回复、转发，草稿管理，监听新邮件            |
+| `lark-contact`                  | 按姓名/邮箱/手机号搜索用户，获取用户信息                     |
+| `lark-wiki`                     | 知识空间、节点、文档                                |
+| `lark-event`                    | 实时事件订阅（WebSocket），支持正则路由与 Agent 友好格式      |
+| `lark-vc`                       | 搜索会议记录、查询会议纪要产物（总结、待办、逐字稿）                |
+| `lark-whiteboard`               | 画板/图表 DSL 渲染                              |
+| `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节）                    |
+| `lark-openapi-explorer`         | 从官方文档探索底层 API                             |
+| `lark-skill-maker`              | 自定义 skill 创建框架                            |
+| `lark-approval`                 | 审批任务查询、同意/拒绝/转交审批任务、撤回与抄送审批实例             |
+| `lark-workflow-meeting-summary` | 工作流：会议纪要汇总与结构化报告                          |
+| `lark-workflow-standup-report`  | 工作流：日程待办摘要                                |
 
 ## 认证
 
@@ -251,6 +268,10 @@ lark-cli schema im.messages.delete
 
 请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/cli&type=Date)](https://star-history.com/#larksuite/cli&Date)
+
 ## 贡献
 
 欢迎社区贡献！如果你发现 bug 或有功能建议，请提交 [Issue](https://github.com/larksuite/cli/issues) 或 [Pull Request](https://github.com/larksuite/cli/pulls)。

cmd/api/api.go

@@ -40,6 +40,7 @@ type APIOptions struct {
 	PageLimit int
 	PageDelay int
 	Format    string
+	JqExpr    string
 	DryRun    bool
 }
 
@@ -96,6 +97,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
+	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 
 	cmd.ValidArgsFunction = func(_ *cobra.Command, args []string, _ string) ([]string, cobra.ShellCompDirective) {
@@ -155,6 +157,9 @@ func apiRun(opts *APIOptions) error {
 	if opts.PageAll && opts.Output != "" {
 		return output.ErrValidation("--output and --page-all are mutually exclusive")
 	}
+	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
+		return err
+	}
 
 	request, err := buildAPIRequest(opts)
 	if err != nil {
@@ -184,7 +189,7 @@ func apiRun(opts *APIOptions) error {
 	}
 
 	if opts.PageAll {
-		return apiPaginate(opts.Ctx, ac, request, format, out, f.IOStreams.ErrOut,
+		return apiPaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut,
 			client.PaginationOptions{PageLimit: opts.PageLimit, PageDelay: opts.PageDelay})
 	}
 
@@ -195,25 +200,31 @@ func apiRun(opts *APIOptions) error {
 	err = client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath: opts.Output,
 		Format:     format,
+		JqExpr:     opts.JqExpr,
 		Out:        out,
 		ErrOut:     f.IOStreams.ErrOut,
 	})
-	// MarkRaw tells root error handler that the API response was already written
-	// to stdout, so it should skip the stderr error envelope. Only apply when
-	// HandleResponse actually wrote output (i.e. returned a business/API error
-	// after printing JSON to stdout). Non-JSON HTTP errors (e.g. 404 text/plain)
-	// produce no stdout output and need the envelope.
-	if err != nil && client.IsJSONContentType(resp.Header.Get("Content-Type")) {
+	// MarkRaw tells root error handler to skip enrichPermissionError,
+	// preserving the original API error detail (log_id, troubleshooter, etc.).
+	if err != nil {
 		return output.MarkRaw(err)
 	}
-	return err
+	return nil
 }
 
 func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, format string) error {
 	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
 }
 
-func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, out, errOut io.Writer, pagOpts client.PaginationOptions) error {
+func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions) error {
+	// When jq is set, always aggregate all pages then filter.
+	if jqExpr != "" {
+		if err := client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, client.CheckLarkResponse); err != nil {
+			return output.MarkRaw(err)
+		}
+		return nil
+	}
+
 	switch format {
 	case output.FormatNDJSON, output.FormatTable, output.FormatCSV:
 		pf := output.NewPaginatedFormatter(out, format)

cmd/api/api_test.go

@@ -446,10 +446,9 @@ func TestApiCmd_APIError_IsRaw(t *testing.T) {
 		t.Error("expected API error from api command to be marked Raw")
 	}
 
-	// stderr should NOT contain an error envelope (identity line is OK)
-	if strings.Contains(stderr.String(), `"ok"`) {
-		t.Error("expected no JSON error envelope on stderr for Raw API error")
-	}
+	// Note: stderr envelope output is tested at the root level (TestHandleRootError_*)
+	// since WriteErrorEnvelope is called by handleRootError, not by cobra's Execute.
+	_ = stderr
 }
 
 func TestApiCmd_APIError_PreservesOriginalMessage(t *testing.T) {
@@ -537,6 +536,179 @@ func TestApiCmd_PageAll_APIError_IsRaw(t *testing.T) {
 	}
 }
 
+func TestApiCmd_JqFlag_Parsing(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *APIOptions
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--jq", ".data"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts.JqExpr != ".data" {
+		t.Errorf("expected JqExpr=.data, got %s", gotOpts.JqExpr)
+	}
+}
+
+func TestApiCmd_JqFlag_ShortForm(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *APIOptions
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "-q", ".data"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts.JqExpr != ".data" {
+		t.Errorf("expected JqExpr=.data, got %s", gotOpts.JqExpr)
+	}
+}
+
+func TestApiCmd_JqAndOutputConflict(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+		return apiRun(opts)
+	})
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--output", "file.bin"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for --jq + --output conflict")
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Errorf("expected 'mutually exclusive' error, got: %v", err)
+	}
+}
+
+func TestApiCmd_JqFilter_AppliesExpression(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-jq", AppSecret: "test-secret-jq", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/auth/v3/tenant_access_token/internal",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"tenant_access_token": "t-test-token-jq", "expire": 7200,
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/test/jq",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{"name": "Alice"},
+					map[string]interface{}{"name": "Bob"},
+				},
+			},
+		},
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test/jq", "--as", "bot", "--jq", ".data.items[].name"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "Alice") || !strings.Contains(out, "Bob") {
+		t.Errorf("expected jq-filtered names, got: %s", out)
+	}
+	// Should NOT contain the full envelope structure
+	if strings.Contains(out, `"code"`) {
+		t.Errorf("expected jq to filter out envelope, got: %s", out)
+	}
+}
+
+func TestApiCmd_JqAndFormatConflict(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+		return apiRun(opts)
+	})
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--format", "ndjson"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for --jq + --format ndjson conflict")
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Errorf("expected 'mutually exclusive' error, got: %v", err)
+	}
+}
+
+func TestApiCmd_JqInvalidExpression(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+		return apiRun(opts)
+	})
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", "invalid["})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for invalid jq expression")
+	}
+	if !strings.Contains(err.Error(), "invalid jq expression") {
+		t.Errorf("expected 'invalid jq expression' error, got: %v", err)
+	}
+}
+
+func TestApiCmd_PageAll_WithJq(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-pjq", AppSecret: "test-secret-pjq", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/auth/v3/tenant_access_token/internal",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"tenant_access_token": "t-test-token-pjq", "expire": 7200,
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/contact/v3/users",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items":    []interface{}{map[string]interface{}{"id": "u1"}, map[string]interface{}{"id": "u2"}},
+				"has_more": false,
+			},
+		},
+	})
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--jq", ".data.items[].id"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "u1") || !strings.Contains(out, "u2") {
+		t.Errorf("expected jq-filtered ids, got: %s", out)
+	}
+	if strings.Contains(out, `"code"`) {
+		t.Errorf("expected jq to filter out envelope, got: %s", out)
+	}
+}
+
 func TestApiCmd_MethodUppercase(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,

cmd/auth/auth.go

@@ -14,6 +14,7 @@ import (
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 	"github.com/spf13/cobra"
 
+	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 )
 
@@ -48,7 +49,7 @@ type userInfoResponse struct {
 func getUserInfo(ctx context.Context, sdk *lark.Client, accessToken string) (openId, name string, err error) {
 	apiResp, err := sdk.Do(ctx, &larkcore.ApiReq{
 		HttpMethod:                http.MethodGet,
-		ApiPath:                   "/open-apis/authen/v1/user_info",
+		ApiPath:                   larkauth.PathUserInfoV1,
 		SupportedAccessTokenTypes: []larkcore.AccessTokenType{larkcore.AccessTokenTypeUser},
 	}, larkcore.WithUserAccessToken(accessToken))
 	if err != nil {
@@ -109,7 +110,7 @@ func getAppInfo(ctx context.Context, f *cmdutil.Factory, appId string) (*appInfo
 
 	apiResp, err := sdk.Do(ctx, &larkcore.ApiReq{
 		HttpMethod:                http.MethodGet,
-		ApiPath:                   "/open-apis/application/v6/applications/" + appId,
+		ApiPath:                   larkauth.ApplicationInfoPath(appId),
 		QueryParams:               queryParams,
 		SupportedAccessTokenTypes: []larkcore.AccessTokenType{larkcore.AccessTokenTypeTenant},
 	})

cmd/auth/login.go

@@ -90,6 +90,7 @@ func completeDomain(toComplete string) []string {
 	return completions
 }
 
+// authLoginRun executes the login command logic.
 func authLoginRun(opts *LoginOptions) error {
 	f := opts.Factory
 
@@ -225,26 +226,34 @@ func authLoginRun(opts *LoginOptions) error {
 
 	// --no-wait: return immediately with device code and URL
 	if opts.NoWait {
-		b, _ := json.Marshal(map[string]interface{}{
+		data := map[string]interface{}{
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
 			"hint":             fmt.Sprintf("Show verification_url to user, then immediately execute: lark-cli auth login --device-code %s (blocks until authorized or timeout). Do not instruct the user to run this command themselves.", authResp.DeviceCode),
-		})
-		fmt.Fprintln(f.IOStreams.Out, string(b))
+		}
+		encoder := json.NewEncoder(f.IOStreams.Out)
+		encoder.SetEscapeHTML(false)
+		if err := encoder.Encode(data); err != nil {
+			fmt.Fprintf(f.IOStreams.ErrOut, "error: failed to write JSON output: %v\n", err)
+		}
 		return nil
 	}
 
 	// Step 2: Show user code and verification URL
 	if opts.JSON {
-		b, _ := json.Marshal(map[string]interface{}{
+		data := map[string]interface{}{
 			"event":                     "device_authorization",
 			"verification_uri":          authResp.VerificationUri,
 			"verification_uri_complete": authResp.VerificationUriComplete,
 			"user_code":                 authResp.UserCode,
 			"expires_in":                authResp.ExpiresIn,
-		})
-		fmt.Fprintln(f.IOStreams.Out, string(b))
+		}
+		encoder := json.NewEncoder(f.IOStreams.Out)
+		encoder.SetEscapeHTML(false)
+		if err := encoder.Encode(data); err != nil {
+			fmt.Fprintf(f.IOStreams.ErrOut, "error: failed to write JSON output: %v\n", err)
+		}
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)

cmd/doctor/doctor.go

@@ -14,9 +14,11 @@ import (
 	"github.com/spf13/cobra"
 
 	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/update"
 )
 
 // DoctorOptions holds inputs for the doctor command.
@@ -60,6 +62,10 @@ func fail(name, msg, hint string) checkResult {
 	return checkResult{Name: name, Status: "fail", Message: msg, Hint: hint}
 }
 
+func warn(name, msg, hint string) checkResult {
+	return checkResult{Name: name, Status: "warn", Message: msg, Hint: hint}
+}
+
 func skip(name, msg string) checkResult {
 	return checkResult{Name: name, Status: "skip", Message: msg}
 }
@@ -68,6 +74,12 @@ func doctorRun(opts *DoctorOptions) error {
 	f := opts.Factory
 	var checks []checkResult
 
+	// ── 0. CLI version & update check ──
+	checks = append(checks, pass("cli_version", build.Version))
+	if !opts.Offline {
+		checks = append(checks, checkCLIUpdate()...)
+	}
+
 	// ── 1. Config file ──
 	_, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -214,6 +226,23 @@ func mustHTTPClient(f *cmdutil.Factory) *http.Client {
 	return c
 }
 
+// checkCLIUpdate actively queries the npm registry for the latest version.
+// Unlike the root-level async check, this does a synchronous fetch with timeout
+// and works regardless of build version (dev builds included).
+func checkCLIUpdate() []checkResult {
+	latest, err := update.FetchLatest()
+	if err != nil {
+		return []checkResult{warn("cli_update", "check failed: "+err.Error(), "")}
+	}
+	current := build.Version
+	if update.IsNewer(latest, current) {
+		return []checkResult{warn("cli_update",
+			fmt.Sprintf("%s → %s available", current, latest),
+			"run: npm update -g @larksuite/cli")}
+	}
+	return []checkResult{pass("cli_update", latest+" (up to date)")}
+}
+
 func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 	allOK := true
 	for _, c := range checks {

cmd/root.go

@@ -4,11 +4,13 @@
 package cmd
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net/url"
+	"os"
 	"strconv"
 
 	"github.com/larksuite/cli/cmd/api"
@@ -24,6 +26,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/update"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -58,6 +61,8 @@ FLAGS:
     --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
     --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
     -o, --output <path>   output file path for binary responses
+    --jq <expr>           jq expression to filter JSON output
+    -q <expr>             shorthand for --jq
     --dry-run             print request without executing
 
 AI AGENT SKILLS:
@@ -65,7 +70,7 @@ AI AGENT SKILLS:
     teach the agent Lark API patterns, best practices, and workflows.
 
     Install all skills:
-        npx skills add larksuite/cli --all -y
+        npx skills add larksuite/cli -g -y
 
     Or pick specific domains:
         npx skills add larksuite/cli -s lark-calendar -y
@@ -105,12 +110,68 @@ func Execute() int {
 	service.RegisterServiceCommands(rootCmd, f)
 	shortcuts.RegisterShortcuts(rootCmd, f)
 
+	// --- Update check (non-blocking) ---
+	if !isCompletionCommand(os.Args) {
+		setupUpdateNotice()
+	}
+
 	if err := rootCmd.Execute(); err != nil {
 		return handleRootError(f, err)
 	}
 	return 0
 }
 
+// setupUpdateNotice starts an async update check and wires the output decorator.
+func setupUpdateNotice() {
+	// Sync: check cache immediately (no network, fast).
+	if info := update.CheckCached(build.Version); info != nil {
+		update.SetPending(info)
+	}
+
+	// Async: refresh cache for this run (and future runs).
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
+			}
+		}()
+		update.RefreshCache(build.Version)
+		// If cache was just populated for the first time, set pending now.
+		if update.GetPending() == nil {
+			if info := update.CheckCached(build.Version); info != nil {
+				update.SetPending(info)
+			}
+		}
+	}()
+
+	// Wire the output decorator so JSON envelopes include "_notice".
+	output.PendingNotice = func() map[string]interface{} {
+		info := update.GetPending()
+		if info == nil {
+			return nil
+		}
+		return map[string]interface{}{
+			"update": map[string]interface{}{
+				"current": info.Current,
+				"latest":  info.Latest,
+				"message": info.Message(),
+			},
+		}
+	}
+}
+
+// isCompletionCommand returns true if args indicate a shell completion request.
+// Update notifications must be suppressed for these to avoid corrupting
+// machine-parseable completion output.
+func isCompletionCommand(args []string) bool {
+	for _, arg := range args {
+		if arg == "completion" || arg == "__complete" {
+			return true
+		}
+	}
+	return false
+}
+
 // handleRootError dispatches a command error to the appropriate handler
 // and returns the process exit code.
 func handleRootError(f *cmdutil.Factory, err error) int {
@@ -126,12 +187,11 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 
 	// All other structured errors normalize to ExitError.
 	if exitErr := asExitError(err); exitErr != nil {
-		if exitErr.Raw {
-			// Raw errors (e.g. from `api` command) already printed the full API
-			// response to stdout; skip enrichment and duplicate stderr envelope.
-			return exitErr.Code
+		if !exitErr.Raw {
+			// Raw errors (e.g. from `api` command) preserve the original API
+			// error detail; skip enrichment which would clear it.
+			enrichPermissionError(f, exitErr)
 		}
-		enrichPermissionError(f, exitErr)
 		output.WriteErrorEnvelope(errOut, exitErr, string(f.ResolvedIdentity))
 		return exitErr.Code
 	}
@@ -184,12 +244,18 @@ func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyErr
 	}
 
 	env := map[string]interface{}{"ok": false, "error": errData}
-	b, err := json.MarshalIndent(env, "", "  ")
+
+	buffer := &bytes.Buffer{}
+	encoder := json.NewEncoder(buffer)
+	encoder.SetEscapeHTML(false)
+	encoder.SetIndent("", "  ")
+	err := encoder.Encode(env)
+
 	if err != nil {
 		fmt.Fprintln(w, `{"ok":false,"error":{"type":"internal_error","code":"marshal_error","message":"failed to marshal error"}}`)
 		return
 	}
-	fmt.Fprintln(w, string(b))
+	fmt.Fprint(w, buffer.String())
 }
 
 // installTipsHelpFunc wraps the default help function to append a TIPS section

cmd/root_e2e_test.go

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/cmd/api"
+	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts"
+	"github.com/spf13/cobra"
+)
+
+// buildTestRootCmd creates a root command with api, service, and shortcut
+// subcommands wired to a test factory, simulating the real CLI command tree.
+func buildTestRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.Command {
+	t.Helper()
+	rootCmd := &cobra.Command{Use: "lark-cli"}
+	rootCmd.SilenceErrors = true
+	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
+		cmd.SilenceUsage = true
+	}
+	rootCmd.AddCommand(api.NewCmdApi(f, nil))
+	service.RegisterServiceCommands(rootCmd, f)
+	shortcuts.RegisterShortcuts(rootCmd, f)
+	return rootCmd
+}
+
+// executeE2E runs a command through the full command tree and handleRootError,
+// returning exit code — matching real CLI behavior.
+func executeE2E(t *testing.T, f *cmdutil.Factory, rootCmd *cobra.Command, args []string) int {
+	t.Helper()
+	rootCmd.SetArgs(args)
+	if err := rootCmd.Execute(); err != nil {
+		return handleRootError(f, err)
+	}
+	return 0
+}
+
+// registerTokenStub registers a tenant_access_token stub so bot auth succeeds.
+func registerTokenStub(reg *httpmock.Registry) {
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/auth/v3/tenant_access_token/internal",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"tenant_access_token": "t-e2e-token", "expire": 7200,
+		},
+	})
+}
+
+// parseEnvelope parses stderr bytes into an ErrorEnvelope.
+func parseEnvelope(t *testing.T, stderr *bytes.Buffer) output.ErrorEnvelope {
+	t.Helper()
+	if stderr.Len() == 0 {
+		t.Fatal("expected non-empty stderr, got empty")
+	}
+	var env output.ErrorEnvelope
+	if err := json.Unmarshal(stderr.Bytes(), &env); err != nil {
+		t.Fatalf("failed to parse stderr as ErrorEnvelope: %v\nstderr: %s", err, stderr.String())
+	}
+	return env
+}
+
+// assertEnvelope verifies exit code, stdout is empty, and stderr matches the
+// expected ErrorEnvelope exactly via reflect.DeepEqual.
+func assertEnvelope(t *testing.T, code int, wantCode int, stdout *bytes.Buffer, stderr *bytes.Buffer, want output.ErrorEnvelope) {
+	t.Helper()
+	if code != wantCode {
+		t.Errorf("exit code: got %d, want %d", code, wantCode)
+	}
+	if stdout.Len() != 0 {
+		t.Errorf("expected empty stdout, got:\n%s", stdout.String())
+	}
+	got := parseEnvelope(t, stderr)
+	if !reflect.DeepEqual(got, want) {
+		gotJSON, _ := json.MarshalIndent(got, "", "  ")
+		wantJSON, _ := json.MarshalIndent(want, "", "  ")
+		t.Errorf("stderr envelope mismatch:\ngot:\n%s\nwant:\n%s", gotJSON, wantJSON)
+	}
+}
+
+// --- api command ---
+
+func TestE2E_Api_BusinessError_OutputsEnvelope(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "e2e-api-err", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	registerTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/im/v1/messages",
+		Body: map[string]interface{}{
+			"code": 230002,
+			"msg":  "Bot/User can NOT be out of the chat.",
+			"error": map[string]interface{}{
+				"log_id": "test-log-id-001",
+			},
+		},
+	})
+
+	rootCmd := buildTestRootCmd(t, f)
+	code := executeE2E(t, f, rootCmd, []string{
+		"api", "--as", "bot", "POST", "/open-apis/im/v1/messages",
+		"--params", `{"receive_id_type":"chat_id"}`,
+		"--data", `{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"test\"}"}`,
+	})
+
+	// api uses MarkRaw: detail preserved, no enrichment
+	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
+		OK:       false,
+		Identity: "bot",
+		Error: &output.ErrDetail{
+			Type:    "api_error",
+			Code:    230002,
+			Message: "API error: [230002] Bot/User can NOT be out of the chat.",
+			Detail: map[string]interface{}{
+				"log_id": "test-log-id-001",
+			},
+		},
+	})
+}
+
+func TestE2E_Api_PermissionError_NotEnriched(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "e2e-api-perm", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	registerTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/test/perm",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "scope not enabled for this app",
+			"error": map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "calendar:calendar:readonly"},
+				},
+				"log_id": "test-log-id-perm",
+			},
+		},
+	})
+
+	rootCmd := buildTestRootCmd(t, f)
+	code := executeE2E(t, f, rootCmd, []string{
+		"api", "--as", "bot", "GET", "/open-apis/test/perm",
+	})
+
+	// api uses MarkRaw: enrichment skipped, detail preserved, no console_url
+	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
+		OK:       false,
+		Identity: "bot",
+		Error: &output.ErrDetail{
+			Type:    "permission",
+			Code:    99991672,
+			Message: "Permission denied [99991672]",
+			Hint:    "check app permissions or re-authorize: lark-cli auth login",
+			Detail: map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "calendar:calendar:readonly"},
+				},
+				"log_id": "test-log-id-perm",
+			},
+		},
+	})
+}
+
+// --- service command ---
+
+func TestE2E_Service_BusinessError_OutputsEnvelope(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "e2e-svc-err", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	registerTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/im/v1/chats/oc_fake",
+		Body: map[string]interface{}{
+			"code": 99992356,
+			"msg":  "id not exist",
+			"error": map[string]interface{}{
+				"log_id": "test-log-id-svc",
+			},
+		},
+	})
+
+	rootCmd := buildTestRootCmd(t, f)
+	code := executeE2E(t, f, rootCmd, []string{
+		"im", "chats", "get", "--params", `{"chat_id":"oc_fake"}`, "--as", "bot",
+	})
+
+	// service: no MarkRaw, non-permission error — detail preserved
+	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
+		OK:       false,
+		Identity: "bot",
+		Error: &output.ErrDetail{
+			Type:    "api_error",
+			Code:    99992356,
+			Message: "API error: [99992356] id not exist",
+			Detail: map[string]interface{}{
+				"log_id": "test-log-id-svc",
+			},
+		},
+	})
+}
+
+func TestE2E_Service_PermissionError_Enriched(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "e2e-svc-perm", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	registerTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/im/v1/chats/oc_test",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "scope not enabled",
+			"error": map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "im:chat:readonly"},
+				},
+			},
+		},
+	})
+
+	rootCmd := buildTestRootCmd(t, f)
+	code := executeE2E(t, f, rootCmd, []string{
+		"im", "chats", "get", "--params", `{"chat_id":"oc_test"}`, "--as", "bot",
+	})
+
+	// service: no MarkRaw — enrichment applied, detail cleared, console_url set
+	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
+		OK:       false,
+		Identity: "bot",
+		Error: &output.ErrDetail{
+			Type:       "permission",
+			Code:       99991672,
+			Message:    "App scope not enabled: required scope im:chat:readonly [99991672]",
+			Hint:       "enable the scope in developer console (see console_url)",
+			ConsoleURL: "https://open.feishu.cn/page/scope-apply?clientID=e2e-svc-perm&scopes=im%3Achat%3Areadonly",
+		},
+	})
+}
+
+// --- shortcut command ---
+
+func TestE2E_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "e2e-sc-err", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	registerTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		URL:    "/open-apis/im/v1/messages",
+		Status: 400,
+		Body: map[string]interface{}{
+			"code": 230002,
+			"msg":  "Bot/User can NOT be out of the chat.",
+		},
+	})
+
+	rootCmd := buildTestRootCmd(t, f)
+	code := executeE2E(t, f, rootCmd, []string{
+		"im", "+messages-send", "--as", "bot", "--chat-id", "oc_xxx", "--text", "test",
+	})
+
+	// shortcut: no MarkRaw, no HandleResponse — error via DoAPIJSON path
+	assertEnvelope(t, code, output.ExitAPI, stdout, stderr, output.ErrorEnvelope{
+		OK:       false,
+		Identity: "bot",
+		Error: &output.ErrDetail{
+			Type:    "api_error",
+			Code:    230002,
+			Message: "HTTP 400: Bot/User can NOT be out of the chat.",
+		},
+	})
+}

cmd/root_test.go

@@ -65,7 +65,7 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 	}
 }
 
-func TestHandleRootError_RawError_SkipsEnrichmentAndEnvelope(t *testing.T) {
+func TestHandleRootError_RawError_SkipsEnrichmentButWritesEnvelope(t *testing.T) {
 	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
@@ -82,9 +82,9 @@ func TestHandleRootError_RawError_SkipsEnrichmentAndEnvelope(t *testing.T) {
 	if code != output.ExitAPI {
 		t.Errorf("expected exit code %d, got %d", output.ExitAPI, code)
 	}
-	// stderr should be empty — no envelope written
-	if stderr.Len() != 0 {
-		t.Errorf("expected empty stderr for Raw error, got: %s", stderr.String())
+	// stderr should contain the error envelope
+	if stderr.Len() == 0 {
+		t.Error("expected non-empty stderr for Raw error — WriteErrorEnvelope should always run")
 	}
 	// The message should NOT have been enriched by enrichPermissionError
 	// (ErrAPI sets "Permission denied [code]" but enrichment would replace it with "App scope not enabled: ...")

cmd/service/service.go

@@ -109,6 +109,7 @@ type ServiceMethodOptions struct {
 	PageLimit int
 	PageDelay int
 	Format    string
+	JqExpr    string
 	DryRun    bool
 }
 
@@ -157,6 +158,7 @@ func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
+	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
 
 	_ = cmd.RegisterFlagCompletionFunc("as", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
@@ -185,6 +187,9 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	if opts.PageAll && opts.Output != "" {
 		return output.ErrValidation("--output and --page-all are mutually exclusive")
 	}
+	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
+		return err
+	}
 
 	config, err := f.ResolveConfig(opts.As)
 	if err != nil {
@@ -223,7 +228,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	checkErr := scopeAwareChecker(scopes, opts.As.IsBot())
 
 	if opts.PageAll {
-		return servicePaginate(opts.Ctx, ac, request, format, out, f.IOStreams.ErrOut,
+		return servicePaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut,
 			client.PaginationOptions{PageLimit: opts.PageLimit, PageDelay: opts.PageDelay}, checkErr)
 	}
 
@@ -234,6 +239,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 	return client.HandleResponse(resp, client.ResponseOptions{
 		OutputPath: opts.Output,
 		Format:     format,
+		JqExpr:     opts.JqExpr,
 		Out:        out,
 		ErrOut:     f.IOStreams.ErrOut,
 		CheckError: checkErr,
@@ -400,7 +406,12 @@ func scopeAwareChecker(scopes []interface{}, isBotMode bool) func(interface{}) e
 	}
 }
 
-func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, out, errOut io.Writer, pagOpts client.PaginationOptions, checkErr func(interface{}) error) error {
+func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, pagOpts client.PaginationOptions, checkErr func(interface{}) error) error {
+	// When jq is set, always aggregate all pages then filter.
+	if jqExpr != "" {
+		return client.PaginateWithJq(ctx, ac, request, jqExpr, out, pagOpts, checkErr)
+	}
+
 	switch format {
 	case output.FormatNDJSON, output.FormatTable, output.FormatCSV:
 		pf := output.NewPaginatedFormatter(out, format)

cmd/service/service_test.go

@@ -474,6 +474,173 @@ func TestServiceMethod_UnknownFormat_Warning(t *testing.T) {
 	}
 }
 
+// ── jq flag ──
+
+func TestNewCmdServiceMethod_JqFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+
+	var captured *ServiceMethodOptions
+	cmd := NewCmdServiceMethod(f, driveSpec(),
+		map[string]interface{}{"description": "desc", "httpMethod": "GET"}, "list", "files",
+		func(opts *ServiceMethodOptions) error {
+			captured = opts
+			return nil
+		})
+	cmd.SetArgs([]string{"--jq", ".data"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if captured == nil {
+		t.Fatal("runF was not called")
+	}
+	if captured.JqExpr != ".data" {
+		t.Errorf("expected JqExpr=.data, got %s", captured.JqExpr)
+	}
+}
+
+func TestNewCmdServiceMethod_JqShortForm(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+
+	var captured *ServiceMethodOptions
+	cmd := NewCmdServiceMethod(f, driveSpec(),
+		map[string]interface{}{"description": "desc", "httpMethod": "GET"}, "list", "files",
+		func(opts *ServiceMethodOptions) error {
+			captured = opts
+			return nil
+		})
+	cmd.SetArgs([]string{"-q", ".data"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if captured.JqExpr != ".data" {
+		t.Errorf("expected JqExpr=.data, got %s", captured.JqExpr)
+	}
+}
+
+func TestServiceMethod_JqAndOutputConflict(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	spec := map[string]interface{}{
+		"name": "svc", "servicePath": "/open-apis/svc/v1",
+	}
+	method := map[string]interface{}{"path": "items", "httpMethod": "GET"}
+	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
+	cmd.SetArgs([]string{"--jq", ".data", "--output", "file.bin", "--as", "bot"})
+
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for --jq + --output conflict")
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Errorf("expected 'mutually exclusive' error, got: %v", err)
+	}
+}
+
+func TestServiceMethod_JqFilter_AppliesExpression(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-jq", AppSecret: "test-secret-jq", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(tokenStub())
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/svc/v1/items",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{"name": "Alice"},
+					map[string]interface{}{"name": "Bob"},
+				},
+			},
+		},
+	})
+
+	spec := map[string]interface{}{"name": "svc", "servicePath": "/open-apis/svc/v1"}
+	method := map[string]interface{}{"path": "items", "httpMethod": "GET", "parameters": map[string]interface{}{}}
+	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
+	cmd.SetArgs([]string{"--as", "bot", "--jq", ".data.items[].name"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "Alice") || !strings.Contains(out, "Bob") {
+		t.Errorf("expected jq-filtered names, got: %s", out)
+	}
+	if strings.Contains(out, `"code"`) {
+		t.Errorf("expected jq to filter out envelope, got: %s", out)
+	}
+}
+
+func TestServiceMethod_JqAndFormatConflict(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	spec := map[string]interface{}{
+		"name": "svc", "servicePath": "/open-apis/svc/v1",
+	}
+	method := map[string]interface{}{"path": "items", "httpMethod": "GET"}
+	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
+	cmd.SetArgs([]string{"--jq", ".data", "--format", "ndjson", "--as", "bot"})
+
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for --jq + --format ndjson conflict")
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Errorf("expected 'mutually exclusive' error, got: %v", err)
+	}
+}
+
+func TestServiceMethod_JqInvalidExpression(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	spec := map[string]interface{}{
+		"name": "svc", "servicePath": "/open-apis/svc/v1",
+	}
+	method := map[string]interface{}{"path": "items", "httpMethod": "GET"}
+	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
+	cmd.SetArgs([]string{"--jq", "invalid[", "--as", "bot"})
+
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error for invalid jq expression")
+	}
+	if !strings.Contains(err.Error(), "invalid jq expression") {
+		t.Errorf("expected 'invalid jq expression' error, got: %v", err)
+	}
+}
+
+func TestServiceMethod_PageAll_WithJq(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app-spjq", AppSecret: "test-secret-spjq", Brand: core.BrandFeishu,
+	})
+
+	reg.Register(tokenStub())
+	reg.Register(&httpmock.Stub{
+		URL: "/open-apis/svc/v1/items",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items":    []interface{}{map[string]interface{}{"id": "s1"}, map[string]interface{}{"id": "s2"}},
+				"has_more": false,
+			},
+		},
+	})
+
+	spec := map[string]interface{}{"name": "svc", "servicePath": "/open-apis/svc/v1"}
+	method := map[string]interface{}{"path": "items", "httpMethod": "GET", "parameters": map[string]interface{}{}}
+	cmd := NewCmdServiceMethod(f, spec, method, "list", "items", nil)
+	cmd.SetArgs([]string{"--as", "bot", "--page-all", "--jq", ".data.items[].id"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "s1") || !strings.Contains(out, "s2") {
+		t.Errorf("expected jq-filtered ids, got: %s", out)
+	}
+	if strings.Contains(out, `"code"`) {
+		t.Errorf("expected jq to filter out envelope, got: %s", out)
+	}
+}
+
 // ── scopeAwareChecker ──
 
 func TestScopeAwareChecker_Success(t *testing.T) {

go.mod

@@ -7,10 +7,13 @@ require (
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
+	github.com/itchyny/gojq v0.12.17
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1
 	github.com/spf13/cobra v1.10.2
+	github.com/stretchr/testify v1.11.1
+	github.com/tidwall/gjson v1.18.0
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/net v0.33.0
 	golang.org/x/sys v0.33.0
@@ -30,6 +33,7 @@ require (
 	github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/danieljoos/wincred v1.2.3 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
@@ -37,6 +41,7 @@ require (
 	github.com/gopherjs/gopherjs v1.17.2 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/itchyny/timefmt-go v0.1.6 // indirect
 	github.com/jtolds/gls v4.20.0+incompatible // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -46,9 +51,13 @@ require (
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/smarty/assertions v1.15.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/sync v0.15.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -61,6 +61,10 @@ github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWm
 github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/itchyny/gojq v0.12.17 h1:8av8eGduDb5+rvEdaOO+zQUjA04MS0m3Ps8HiD+fceg=
+github.com/itchyny/gojq v0.12.17/go.mod h1:WBrEMkgAfAGO1LUcGOckBl5O726KPp+OlkKug0I/FEY=
+github.com/itchyny/timefmt-go v0.1.6 h1:ia3s54iciXDdzWzwaVKXZPbiXzxxnv1SPGFfM/myJ5Q=
+github.com/itchyny/timefmt-go v0.1.6/go.mod h1:RRDZYC5s9ErkjQvTvvU7keJjxUYzIISJGxm9/mAERQg=
 github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
 github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
@@ -103,6 +107,12 @@ github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0 h1:RWIZEg2iJ8/g6fDDYzMpobmaoGh5OLl4AXtGUGPcqCs=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=

internal/auth/app_registration.go

@@ -47,7 +47,7 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOu
 
 	ep := core.ResolveEndpoints(brand)
 	regEp := core.ResolveEndpoints(core.BrandFeishu) // registration begin always uses feishu
-	endpoint := regEp.Accounts + "/oauth/v1/app/registration"
+	endpoint := regEp.Accounts + PathAppRegistration
 
 	form := url.Values{}
 	form.Set("action", "begin")
@@ -66,6 +66,7 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOu
 		return nil, err
 	}
 	defer resp.Body.Close()
+	logHTTPResponse(resp)
 
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
@@ -129,7 +130,7 @@ func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand cor
 	const maxPollAttempts = 200
 
 	ep := core.ResolveEndpoints(brand)
-	endpoint := ep.Accounts + "/oauth/v1/app/registration"
+	endpoint := ep.Accounts + PathAppRegistration
 	deadline := time.Now().Add(time.Duration(expiresIn) * time.Second)
 	currentInterval := interval
 	attempts := 0
@@ -162,6 +163,7 @@ func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand cor
 			currentInterval = minInt(currentInterval+1, maxPollInterval)
 			continue
 		}
+		logHTTPResponse(resp)
 
 		body, err := io.ReadAll(resp.Body)
 		resp.Body.Close()

internal/auth/app_registration_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/smartystreets/goconvey/convey"
 )
 
+// Test_BuildVerificationURL verifies that tracking parameters are correctly appended.
 func Test_BuildVerificationURL(t *testing.T) {
 	t.Run("URL不含问号则添加?分隔符", func(t *testing.T) {
 		result := BuildVerificationURL("https://example.com/verify", "1.0.0")

internal/auth/auth_response_log.go

@@ -0,0 +1,38 @@
+package auth
+
+import (
+	"net/http"
+
+	"github.com/larksuite/cli/internal/keychain"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+// logHTTPResponse logs the HTTP response details for an authentication request.
+// It extracts the request path, status code, and x-tt-logid from the given HTTP response.
+func logHTTPResponse(resp *http.Response) {
+	if resp == nil {
+		return
+	}
+
+	path := "missing"
+	if resp.Request != nil && resp.Request.URL != nil {
+		path = resp.Request.URL.Path
+	}
+
+	keychain.LogAuthResponse(path, resp.StatusCode, resp.Header.Get("x-tt-logid"))
+}
+
+// logSDKResponse logs the SDK response details for an authentication request.
+// It extracts the status code and x-tt-logid from the given API response object.
+func logSDKResponse(path string, apiResp *larkcore.ApiResp) {
+	if path == "" {
+		path = "missing"
+	}
+
+	if apiResp == nil {
+		keychain.LogAuthResponse(path, 0, "")
+		return
+	}
+
+	keychain.LogAuthResponse(path, apiResp.StatusCode, apiResp.Header.Get("x-tt-logid"))
+}

internal/auth/device_flow.go

@@ -54,8 +54,8 @@ type OAuthEndpoints struct {
 func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints {
 	ep := core.ResolveEndpoints(brand)
 	return OAuthEndpoints{
-		DeviceAuthorization: ep.Accounts + "/oauth/v1/device_authorization",
-		Token:               ep.Open + "/open-apis/authen/v2/oauth/token",
+		DeviceAuthorization: ep.Accounts + PathDeviceAuthorization,
+		Token:               ep.Open + PathOAuthTokenV2,
 	}
 }
 
@@ -93,6 +93,7 @@ func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string
 		return nil, err
 	}
 	defer resp.Body.Close()
+	logHTTPResponse(resp)
 
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
@@ -179,6 +180,7 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 			currentInterval = minInt(currentInterval+1, maxPollInterval)
 			continue
 		}
+		logHTTPResponse(resp)
 
 		body, err := io.ReadAll(resp.Body)
 		resp.Body.Close()
@@ -258,6 +260,7 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 
 // helpers
 
+// minInt returns the smaller of a or b.
 func minInt(a, b int) int {
 	if a < b {
 		return a
@@ -265,6 +268,7 @@ func minInt(a, b int) int {
 	return b
 }
 
+// getStr retrieves a string value from a map, returning an empty string if not found or not a string.
 func getStr(m map[string]interface{}, key string) string {
 	if v, ok := m[key]; ok {
 		if s, ok := v.(string); ok {
@@ -274,6 +278,7 @@ func getStr(m map[string]interface{}, key string) string {
 	return ""
 }
 
+// getInt retrieves an integer value from a map, returning a fallback value if not found or not a number.
 func getInt(m map[string]interface{}, key string, fallback int) int {
 	if v, ok := m[key]; ok {
 		switch n := v.(type) {

internal/auth/device_flow_test.go

@@ -4,11 +4,20 @@
 package auth
 
 import (
+	"bytes"
+	"fmt"
+	"log"
+	"net/http"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/keychain"
 )
 
+// TestResolveOAuthEndpoints_Feishu validates endpoints for the Feishu brand.
 func TestResolveOAuthEndpoints_Feishu(t *testing.T) {
 	ep := ResolveOAuthEndpoints(core.BrandFeishu)
 	if ep.DeviceAuthorization != "https://accounts.feishu.cn/oauth/v1/device_authorization" {
@@ -19,6 +28,7 @@ func TestResolveOAuthEndpoints_Feishu(t *testing.T) {
 	}
 }
 
+// TestResolveOAuthEndpoints_Lark validates endpoints for the Lark brand.
 func TestResolveOAuthEndpoints_Lark(t *testing.T) {
 	ep := ResolveOAuthEndpoints(core.BrandLark)
 	if ep.DeviceAuthorization != "https://accounts.larksuite.com/oauth/v1/device_authorization" {
@@ -28,3 +38,137 @@ func TestResolveOAuthEndpoints_Lark(t *testing.T) {
 		t.Errorf("Token = %q", ep.Token)
 	}
 }
+
+// TestRequestDeviceAuthorization_LogsResponse checks if API responses are logged correctly.
+func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
+	reg := &httpmock.Registry{}
+	t.Cleanup(func() { reg.Verify(t) })
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    PathDeviceAuthorization,
+		Body: map[string]interface{}{
+			"device_code":               "device-code",
+			"user_code":                 "user-code",
+			"verification_uri":          "https://example.com/verify",
+			"verification_uri_complete": "https://example.com/verify?code=123",
+			"expires_in":                240,
+			"interval":                  5,
+		},
+		Headers: http.Header{
+			"Content-Type": []string{"application/json"},
+			"X-Tt-Logid":   []string{"device-log-id"},
+		},
+	})
+
+	var buf bytes.Buffer
+	restore := keychain.SetAuthLogHooksForTest(log.New(&buf, "", 0), func() time.Time {
+		return time.Date(2026, 4, 2, 3, 4, 5, 0, time.UTC)
+	}, func() []string {
+		return []string{"lark-cli", "auth", "login", "--device-code", "device-code-secret", "--app-secret=top-secret"}
+	})
+	t.Cleanup(restore)
+
+	_, err := RequestDeviceAuthorization(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "", nil)
+	if err != nil {
+		t.Fatalf("RequestDeviceAuthorization() error: %v", err)
+	}
+
+	got := buf.String()
+	if !strings.Contains(got, "time=2026-04-02T03:04:05Z") {
+		t.Fatalf("expected time in log, got %q", got)
+	}
+	if !strings.Contains(got, "path=missing") {
+		t.Fatalf("expected path in log, got %q", got)
+	}
+	if !strings.Contains(got, "status=200") {
+		t.Fatalf("expected status=200 in log, got %q", got)
+	}
+	if !strings.Contains(got, "x-tt-logid=device-log-id") {
+		t.Fatalf("expected x-tt-logid in log, got %q", got)
+	}
+	if !strings.Contains(got, "cmdline=lark-cli auth login ...") {
+		t.Fatalf("expected cmdline in log, got %q", got)
+	}
+}
+
+// TestFormatAuthCmdline_TruncatesExtraArgs verifies that long command lines are truncated.
+func TestFormatAuthCmdline_TruncatesExtraArgs(t *testing.T) {
+	got := keychain.FormatAuthCmdline([]string{
+		"lark-cli",
+		"auth",
+		"login",
+		"--device-code", "device-code-secret",
+		"--app-secret=top-secret",
+		"--scope", "contact:read",
+	})
+
+	want := "lark-cli auth login ..."
+	if got != want {
+		t.Fatalf("formatAuthCmdline() = %q, want %q", got, want)
+	}
+}
+
+// TestLogAuthResponse_IgnoresTypedNilHTTPResponse tests that a typed nil HTTP response is ignored gracefully.
+func TestLogAuthResponse_IgnoresTypedNilHTTPResponse(t *testing.T) {
+	var buf bytes.Buffer
+	restore := keychain.SetAuthLogHooksForTest(log.New(&buf, "", 0), nil, nil)
+	t.Cleanup(restore)
+
+	var resp *http.Response
+	logHTTPResponse(resp)
+
+	if got := buf.String(); got != "" {
+		t.Fatalf("expected no log output, got %q", got)
+	}
+}
+
+// TestLogAuthResponse_HandlesNilSDKResponse verifies that a nil SDK response is handled without panicking.
+func TestLogAuthResponse_HandlesNilSDKResponse(t *testing.T) {
+	var buf bytes.Buffer
+	restore := keychain.SetAuthLogHooksForTest(log.New(&buf, "", 0), func() time.Time {
+		return time.Date(2026, 4, 2, 3, 4, 5, 0, time.UTC)
+	}, func() []string {
+		return []string{"lark-cli", "auth", "status", "--verify"}
+	})
+	t.Cleanup(restore)
+
+	logSDKResponse(PathUserInfoV1, nil)
+
+	got := buf.String()
+	if !strings.Contains(got, "path="+PathUserInfoV1) {
+		t.Fatalf("expected sdk path in log, got %q", got)
+	}
+	if !strings.Contains(got, "status=0") {
+		t.Fatalf("expected zero status in log, got %q", got)
+	}
+}
+
+func TestLogAuthError_RecordsStructuredEntry(t *testing.T) {
+	var buf bytes.Buffer
+	restore := keychain.SetAuthLogHooksForTest(log.New(&buf, "", 0), func() time.Time {
+		return time.Date(2026, 4, 2, 3, 4, 5, 0, time.UTC)
+	}, func() []string {
+		return []string{"lark-cli", "auth", "login", "--device-code", "secret"}
+	})
+	t.Cleanup(restore)
+
+	keychain.LogAuthError("keychain", "Set", fmt.Errorf("keychain Set error: %w", http.ErrUseLastResponse))
+
+	got := buf.String()
+	if !strings.Contains(got, "auth-error") {
+		t.Fatalf("expected auth-error log entry, got %q", got)
+	}
+	if !strings.Contains(got, "component=keychain") {
+		t.Fatalf("expected component in log, got %q", got)
+	}
+	if !strings.Contains(got, "op=Set") {
+		t.Fatalf("expected op in log, got %q", got)
+	}
+	if !strings.Contains(got, "error=\"keychain Set error: net/http: use last response\"") {
+		t.Fatalf("expected quoted error in log, got %q", got)
+	}
+	if !strings.Contains(got, "cmdline=lark-cli auth login ...") {
+		t.Fatalf("expected truncated cmdline in log, got %q", got)
+	}
+}

internal/auth/errors.go

@@ -31,6 +31,7 @@ type NeedAuthorizationError struct {
 	UserOpenId string
 }
 
+// Error returns the error message for NeedAuthorizationError.
 func (e *NeedAuthorizationError) Error() string {
 	return fmt.Sprintf("need_user_authorization (user: %s)", e.UserOpenId)
 }
@@ -44,6 +45,7 @@ type SecurityPolicyError struct {
 	Err          error
 }
 
+// Error returns the error message for SecurityPolicyError.
 func (e *SecurityPolicyError) Error() string {
 	if e.Err != nil {
 		return fmt.Sprintf("security policy error [%d]: %s: %v", e.Code, e.Message, e.Err)
@@ -51,6 +53,7 @@ func (e *SecurityPolicyError) Error() string {
 	return fmt.Sprintf("security policy error [%d]: %s", e.Code, e.Message)
 }
 
+// Unwrap returns the underlying error.
 func (e *SecurityPolicyError) Unwrap() error {
 	return e.Err
 }

internal/auth/paths.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+// Common authentication paths used for logging and API calls.
+const (
+	// PathDeviceAuthorization is the endpoint for device authorization.
+	PathDeviceAuthorization = "/oauth/v1/device_authorization"
+	// PathAppRegistration is the endpoint for application registration.
+	PathAppRegistration = "/oauth/v1/app/registration"
+	// PathOAuthTokenV2 is the endpoint for requesting an OAuth token (v2).
+	PathOAuthTokenV2 = "/open-apis/authen/v2/oauth/token"
+	// PathUserInfoV1 is the endpoint for fetching user information.
+	PathUserInfoV1 = "/open-apis/authen/v1/user_info"
+	// PathApplicationInfoV6Prefix is the prefix endpoint for fetching application info.
+	PathApplicationInfoV6Prefix = "/open-apis/application/v6/applications/"
+)
+
+// ApplicationInfoPath returns the full API path for querying an application's information.
+func ApplicationInfoPath(appId string) string {
+	return PathApplicationInfoV6Prefix + appId
+}

internal/auth/scope_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 )
 
+// TestMissingScopes tests the calculation of missing scopes.
 func TestMissingScopes(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -62,6 +63,7 @@ func TestMissingScopes(t *testing.T) {
 	}
 }
 
+// sliceEqual compares two string slices for equality.
 func sliceEqual(a, b []string) bool {
 	if len(a) == 0 && len(b) == 0 {
 		return true

internal/auth/token_store.go

@@ -25,6 +25,7 @@ type StoredUAToken struct {
 
 const refreshAheadMs = 5 * 60 * 1000 // 5 minutes
 
+// accountKey generates a unique key for an account based on its AppID and UserOpenID.
 func accountKey(appId, userOpenId string) string {
 	return fmt.Sprintf("%s:%s", appId, userOpenId)
 }
@@ -39,8 +40,8 @@ func MaskToken(token string) string {
 
 // GetStoredToken reads the stored UAT for a given (appId, userOpenId) pair.
 func GetStoredToken(appId, userOpenId string) *StoredUAToken {
-	jsonStr := keychain.Get(keychain.LarkCliService, accountKey(appId, userOpenId))
-	if jsonStr == "" {
+	jsonStr, err := keychain.Get(keychain.LarkCliService, accountKey(appId, userOpenId))
+	if err != nil || jsonStr == "" {
 		return nil
 	}
 	var token StoredUAToken

internal/auth/transport.go

@@ -11,6 +11,8 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+
+	"github.com/larksuite/cli/internal/util"
 )
 
 // SecurityPolicyTransport is an http.RoundTripper that intercepts all responses
@@ -19,11 +21,12 @@ type SecurityPolicyTransport struct {
 	Base http.RoundTripper
 }
 
+// base returns the underlying RoundTripper or http.DefaultTransport if nil.
 func (t *SecurityPolicyTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return http.DefaultTransport
+	return util.FallbackTransport()
 }
 
 // RoundTrip implements http.RoundTripper.
@@ -82,6 +85,7 @@ func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response,
 	return resp, nil
 }
 
+// tryHandleMCPResponse attempts to parse a JSON-RPC (MCP) formatted error response.
 func (t *SecurityPolicyTransport) tryHandleMCPResponse(result map[string]interface{}) error {
 	// MCP (JSON-RPC) response format:
 	// {
@@ -130,6 +134,7 @@ func (t *SecurityPolicyTransport) tryHandleMCPResponse(result map[string]interfa
 	return nil
 }
 
+// tryHandleOAPIResponse attempts to parse a standard Lark OpenAPI formatted error response.
 func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interface{}) error {
 	// 1. Extract code
 	code := getInt(result, "code", 0)
@@ -180,6 +185,7 @@ func (t *SecurityPolicyTransport) tryHandleOAPIResponse(result map[string]interf
 	return nil
 }
 
+// isValidChallengeURL checks if the given URL is a valid challenge URL.
 func isValidChallengeURL(rawURL string) bool {
 	if rawURL == "" {
 		return false

internal/auth/uat_client.go

@@ -23,6 +23,7 @@ import (
 
 var safeIDChars = regexp.MustCompile(`[^a-zA-Z0-9._-]`)
 
+// sanitizeID replaces empty IDs with "default" to prevent file path issues.
 func sanitizeID(id string) string {
 	return safeIDChars.ReplaceAllString(id, "_")
 }
@@ -98,6 +99,7 @@ func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string,
 	return "", &NeedAuthorizationError{UserOpenId: opts.UserOpenId}
 }
 
+// refreshWithLock acquires a file lock before attempting to refresh the token.
 func refreshWithLock(httpClient *http.Client, opts UATCallOptions, stored *StoredUAToken) (*StoredUAToken, error) {
 	key := fmt.Sprintf("%s:%s", opts.AppId, opts.UserOpenId)
 
@@ -165,6 +167,7 @@ func refreshWithLock(httpClient *http.Client, opts UATCallOptions, stored *Store
 	return doRefreshToken(httpClient, opts, stored)
 }
 
+// doRefreshToken performs the actual HTTP request to refresh the token.
 func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *StoredUAToken) (*StoredUAToken, error) {
 	errOut := opts.ErrOut
 	if errOut == nil {
@@ -200,6 +203,7 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 			return nil, err
 		}
 		defer resp.Body.Close()
+		logHTTPResponse(resp)
 
 		body, err := io.ReadAll(resp.Body)
 		if err != nil {

internal/auth/uat_client_options_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 )
 
+// TestNewUATCallOptions validates the extraction of options from CLI config.
 func TestNewUATCallOptions(t *testing.T) {
 	cfg := &core.CliConfig{
 		AppID:      "app123",

internal/auth/verify.go

@@ -18,12 +18,13 @@ import (
 func VerifyUserToken(ctx context.Context, sdk *lark.Client, accessToken string) error {
 	apiResp, err := sdk.Do(ctx, &larkcore.ApiReq{
 		HttpMethod:                http.MethodGet,
-		ApiPath:                   "/open-apis/authen/v1/user_info",
+		ApiPath:                   PathUserInfoV1,
 		SupportedAccessTokenTypes: []larkcore.AccessTokenType{larkcore.AccessTokenTypeUser},
 	}, larkcore.WithUserAccessToken(accessToken))
 	if err != nil {
 		return err
 	}
+	logSDKResponse(PathUserInfoV1, apiResp)
 
 	var resp struct {
 		Code int    `json:"code"`

internal/auth/verify_test.go

@@ -4,16 +4,22 @@
 package auth
 
 import (
+	"bytes"
 	"context"
+	"log"
+	"net/http"
 	"strings"
 	"testing"
+	"time"
 
+	"github.com/larksuite/cli/internal/keychain"
 	lark "github.com/larksuite/oapi-sdk-go/v3"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
+// TestVerifyUserToken_TransportError verifies handling of underlying transport errors.
 func TestVerifyUserToken_TransportError(t *testing.T) {
 	reg := &httpmock.Registry{}
 	// Register no stubs — any request will fail with "no stub" error
@@ -28,29 +34,34 @@ func TestVerifyUserToken_TransportError(t *testing.T) {
 	}
 }
 
+// TestVerifyUserToken validates normal and error response paths of the user token validation.
 func TestVerifyUserToken(t *testing.T) {
 	tests := []struct {
 		name      string
 		body      interface{}
 		wantErr   bool
 		errSubstr string
+		wantLog   bool
 	}{
 		{
 			name:    "success",
 			body:    map[string]interface{}{"code": 0, "msg": "ok"},
 			wantErr: false,
+			wantLog: true,
 		},
 		{
 			name:      "token invalid",
 			body:      map[string]interface{}{"code": 99991668, "msg": "invalid token"},
 			wantErr:   true,
 			errSubstr: "[99991668]",
+			wantLog:   true,
 		},
 		{
 			name:      "non-JSON response",
 			body:      "not json",
 			wantErr:   true,
 			errSubstr: "invalid character",
+			wantLog:   false,
 		},
 	}
 
@@ -61,8 +72,12 @@ func TestVerifyUserToken(t *testing.T) {
 
 			reg.Register(&httpmock.Stub{
 				Method: "GET",
-				URL:    "/open-apis/authen/v1/user_info",
+				URL:    PathUserInfoV1,
 				Body:   tt.body,
+				Headers: http.Header{
+					"Content-Type": []string{"application/json"},
+					"X-Tt-Logid":   []string{"verify-log-id"},
+				},
 			})
 
 			sdk := lark.NewClient("test-app", "test-secret",
@@ -70,6 +85,14 @@ func TestVerifyUserToken(t *testing.T) {
 				lark.WithHttpClient(httpmock.NewClient(reg)),
 			)
 
+			var buf bytes.Buffer
+			restore := keychain.SetAuthLogHooksForTest(log.New(&buf, "", 0), func() time.Time {
+				return time.Date(2026, 4, 2, 3, 4, 5, 0, time.UTC)
+			}, func() []string {
+				return []string{"lark-cli", "auth", "status"}
+			})
+			t.Cleanup(restore)
+
 			err := VerifyUserToken(context.Background(), sdk, "test-token")
 			if tt.wantErr {
 				if err == nil {
@@ -83,6 +106,23 @@ func TestVerifyUserToken(t *testing.T) {
 					t.Fatalf("unexpected error: %v", err)
 				}
 			}
+			got := buf.String()
+			if tt.wantLog {
+				if !strings.Contains(got, "path="+PathUserInfoV1) {
+					t.Fatalf("expected path in log, got %q", got)
+				}
+				if !strings.Contains(got, "status=200") {
+					t.Fatalf("expected status=200 in log, got %q", got)
+				}
+				if !strings.Contains(got, "x-tt-logid=verify-log-id") {
+					t.Fatalf("expected x-tt-logid in log, got %q", got)
+				}
+				if !strings.Contains(got, "cmdline=lark-cli auth status") {
+					t.Fatalf("expected cmdline in log, got %q", got)
+				}
+			} else if got != "" {
+				t.Fatalf("expected no log output, got %q", got)
+			}
 		})
 	}
 }

internal/client/pagination.go

@@ -4,6 +4,7 @@
 package client
 
 import (
+	"context"
 	"fmt"
 	"io"
 
@@ -16,6 +17,22 @@ type PaginationOptions struct {
 	PageDelay int // ms, default 200
 }
 
+// PaginateWithJq aggregates all pages, checks for API errors, then applies a jq filter.
+// If checkErr detects an error, the raw result is printed as JSON before returning the error.
+func PaginateWithJq(ctx context.Context, ac *APIClient, request RawApiRequest,
+	jqExpr string, out io.Writer, pagOpts PaginationOptions,
+	checkErr func(interface{}) error) error {
+	result, err := ac.PaginateAll(ctx, request, pagOpts)
+	if err != nil {
+		return output.ErrNetwork("API call failed: %v", err)
+	}
+	if apiErr := checkErr(result); apiErr != nil {
+		output.FormatValue(out, result, output.FormatJSON)
+		return apiErr
+	}
+	return output.JqFilter(out, result, jqExpr)
+}
+
 func mergePagedResults(w io.Writer, results []interface{}) interface{} {
 	if len(results) == 0 {
 		return map[string]interface{}{}

internal/client/response.go

@@ -26,6 +26,7 @@ import (
 type ResponseOptions struct {
 	OutputPath string        // --output flag; "" = auto-detect
 	Format     output.Format // output format for JSON responses
+	JqExpr     string        // if set, apply jq filter instead of Format
 	Out        io.Writer     // stdout
 	ErrOut     io.Writer     // stderr
 	// CheckError is called on parsed JSON results. Nil defaults to CheckLarkResponse.
@@ -62,11 +63,17 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 		if opts.OutputPath != "" {
 			return saveAndPrint(resp, opts.OutputPath, opts.Out)
 		}
+		if opts.JqExpr != "" {
+			return output.JqFilter(opts.Out, result, opts.JqExpr)
+		}
 		output.FormatValue(opts.Out, result, opts.Format)
 		return nil
 	}
 
 	// Non-JSON (binary) responses.
+	if opts.JqExpr != "" {
+		return output.ErrValidation("--jq requires a JSON response (got Content-Type: %s)", ct)
+	}
 	if opts.OutputPath != "" {
 		return saveAndPrint(resp, opts.OutputPath, opts.Out)
 	}

internal/client/response_test.go

@@ -319,6 +319,23 @@ func TestHandleResponse_200TextPlain_SavesFile(t *testing.T) {
 	}
 }
 
+func TestHandleResponse_BinaryWithJq_RejectsNonJSON(t *testing.T) {
+	resp := newApiResp([]byte("PNG DATA"), map[string]string{"Content-Type": "image/png"})
+
+	var out, errOut bytes.Buffer
+	err := HandleResponse(resp, ResponseOptions{
+		JqExpr: ".data",
+		Out:    &out,
+		ErrOut: &errOut,
+	})
+	if err == nil {
+		t.Fatal("expected error when --jq is used with non-JSON response")
+	}
+	if !strings.Contains(err.Error(), "--jq requires a JSON response") {
+		t.Errorf("expected '--jq requires a JSON response' error, got: %v", err)
+	}
+}
+
 func TestHandleResponse_403JSON_CheckLarkResponse(t *testing.T) {
 	body := []byte(`{"code":99991400,"msg":"invalid token"}`)
 	resp := newApiRespWithStatus(403, body, map[string]string{"Content-Type": "application/json"})

internal/cmdutil/factory_default.go

@@ -18,6 +18,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/util"
 )
 
 // NewDefault creates a production Factory with cached closures.
@@ -73,7 +74,9 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 
 func cachedHttpClientFunc() func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
-		var transport = http.DefaultTransport
+		util.WarnIfProxied(os.Stderr)
+
+		var transport http.RoundTripper = util.NewBaseTransport()
 		transport = &RetryTransport{Base: transport}
 		transport = &SecurityHeaderTransport{Base: transport}
 
@@ -98,7 +101,8 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 			lark.WithHeaders(BaseSecurityHeaders()),
 		}
 		// Build SDK transport chain
-		var sdkTransport = http.DefaultTransport
+		util.WarnIfProxied(os.Stderr)
+		var sdkTransport http.RoundTripper = util.NewBaseTransport()
 		sdkTransport = &UserAgentTransport{Base: sdkTransport}
 		sdkTransport = &auth.SecurityPolicyTransport{Base: sdkTransport}
 		opts = append(opts, lark.WithHttpClient(&http.Client{

internal/cmdutil/transport.go

@@ -6,6 +6,8 @@ package cmdutil
 import (
 	"net/http"
 	"time"
+
+	"github.com/larksuite/cli/internal/util"
 )
 
 // RetryTransport is an http.RoundTripper that retries on 5xx responses
@@ -20,7 +22,7 @@ func (t *RetryTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return http.DefaultTransport
+	return util.FallbackTransport()
 }
 
 func (t *RetryTransport) delay() time.Duration {
@@ -65,7 +67,7 @@ func (t *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error
 	if t.Base != nil {
 		return t.Base.RoundTrip(req)
 	}
-	return http.DefaultTransport.RoundTrip(req)
+	return util.FallbackTransport().RoundTrip(req)
 }
 
 // SecurityHeaderTransport is an http.RoundTripper that injects CLI security
@@ -78,7 +80,7 @@ func (t *SecurityHeaderTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return http.DefaultTransport
+	return util.FallbackTransport()
 }
 
 // RoundTrip implements http.RoundTripper.

internal/core/config.go

@@ -5,11 +5,13 @@ package core
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
 
 	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -113,6 +115,12 @@ func RequireConfig(kc keychain.KeychainAccess) (*CliConfig, error) {
 	app := raw.Apps[0]
 	secret, err := ResolveSecretInput(app.AppSecret, kc)
 	if err != nil {
+		// If the error comes from the keychain, it will already be wrapped as an ExitError.
+		// For other errors (e.g. file read errors, unknown sources), wrap them as ConfigError.
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) {
+			return nil, exitErr
+		}
 		return nil, &ConfigError{Code: 2, Type: "config", Message: err.Error()}
 	}
 	cfg := &CliConfig{

internal/keychain/auth_log.go

@@ -0,0 +1,159 @@
+package keychain
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+var (
+	authResponseLogger     *log.Logger
+	authResponseLoggerOnce = &sync.Once{}
+
+	authResponseLogNow  = time.Now
+	authResponseLogArgs = func() []string { return os.Args }
+)
+
+func authLogDir() string {
+	if dir := os.Getenv("LARKSUITE_CLI_CONFIG_DIR"); dir != "" {
+		return filepath.Join(dir, "logs")
+	}
+
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
+	}
+
+	return filepath.Join(home, ".lark-cli", "logs")
+}
+
+func initAuthLogger() {
+	authResponseLoggerOnce.Do(func() {
+		if authResponseLogger != nil {
+			return
+		}
+
+		dir := authLogDir()
+		now := authResponseLogNow()
+		if err := os.MkdirAll(dir, 0700); err != nil {
+			return
+		}
+
+		logName := fmt.Sprintf("auth-%s.log", now.Format("2006-01-02"))
+		logPath := filepath.Join(dir, logName)
+		if f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600); err == nil {
+			authResponseLogger = log.New(f, "", 0)
+			cleanupOldLogs(dir, now)
+		}
+	})
+}
+
+func FormatAuthCmdline(args []string) string {
+	if len(args) == 0 {
+		return ""
+	}
+
+	if len(args) <= 3 {
+		return strings.Join(args, " ")
+	}
+
+	return strings.Join(args[:3], " ") + " ..."
+}
+
+func LogAuthResponse(path string, status int, logID string) {
+	initAuthLogger()
+	if authResponseLogger == nil {
+		return
+	}
+
+	authResponseLogger.Printf(
+		"[lark-cli] auth-response: time=%s path=%s status=%d x-tt-logid=%s cmdline=%s",
+		authResponseLogNow().Format(time.RFC3339Nano),
+		path,
+		status,
+		logID,
+		FormatAuthCmdline(authResponseLogArgs()),
+	)
+}
+
+func LogAuthError(component, op string, err error) {
+	if err == nil {
+		return
+	}
+
+	initAuthLogger()
+	if authResponseLogger == nil {
+		return
+	}
+
+	authResponseLogger.Printf(
+		"[lark-cli] auth-error: time=%s component=%s op=%s error=%q cmdline=%s",
+		authResponseLogNow().Format(time.RFC3339Nano),
+		component,
+		op,
+		err.Error(),
+		FormatAuthCmdline(authResponseLogArgs()),
+	)
+}
+
+func SetAuthLogHooksForTest(logger *log.Logger, now func() time.Time, args func() []string) func() {
+	prevLogger := authResponseLogger
+	prevNow := authResponseLogNow
+	prevArgs := authResponseLogArgs
+	prevOnce := authResponseLoggerOnce
+
+	authResponseLogger = logger
+	authResponseLoggerOnce = &sync.Once{}
+
+	if now != nil {
+		authResponseLogNow = now
+	}
+	if args != nil {
+		authResponseLogArgs = args
+	}
+
+	return func() {
+		authResponseLogger = prevLogger
+		authResponseLogNow = prevNow
+		authResponseLogArgs = prevArgs
+		authResponseLoggerOnce = prevOnce
+	}
+}
+
+func cleanupOldLogs(dir string, now time.Time) {
+	defer func() {
+		if r := recover(); r != nil {
+			fmt.Fprintf(os.Stderr, "[lark-cli] [WARN] background log cleanup panicked: %v\n", r)
+		}
+	}()
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+
+	now = time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
+	cutoff := now.AddDate(0, 0, -7)
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasPrefix(entry.Name(), "auth-") || !strings.HasSuffix(entry.Name(), ".log") {
+			continue
+		}
+
+		dateStr := strings.TrimPrefix(entry.Name(), "auth-")
+		dateStr = strings.TrimSuffix(dateStr, ".log")
+
+		logDate, err := time.Parse("2006-01-02", dateStr)
+		if err != nil {
+			continue
+		}
+
+		logDate = time.Date(logDate.Year(), logDate.Month(), logDate.Day(), 0, 0, 0, 0, now.Location())
+		if logDate.Before(cutoff) {
+			_ = os.Remove(filepath.Join(dir, entry.Name()))
+		}
+	}
+}

internal/keychain/default.go

@@ -3,17 +3,12 @@
 
 package keychain
 
-import "fmt"
-
-// defaultKeychain implements KeychainAccess using the real platform keychain.
+// defaultKeychain is the default implementation of KeychainAccess
+// that uses the package-level functions.
 type defaultKeychain struct{}
 
 func (d *defaultKeychain) Get(service, account string) (string, error) {
-	val := Get(service, account)
-	if val == "" {
-		return "", fmt.Errorf("keychain entry not found: %s/%s", service, account)
-	}
-	return val, nil
+	return Get(service, account)
 }
 
 func (d *defaultKeychain) Set(service, account, value string) error {

internal/keychain/keychain.go

@@ -5,6 +5,21 @@
 // macOS uses the system Keychain; Linux uses AES-256-GCM encrypted files; Windows uses DPAPI + registry.
 package keychain
 
+import (
+	"errors"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/output"
+)
+
+var (
+	// ErrNotFound is returned when the requested credential is not found.
+	ErrNotFound = errors.New("keychain: item not found")
+
+	// errNotInitialized is an internal error indicating the master key is missing or invalid.
+	errNotInitialized = errors.New("keychain not initialized")
+)
+
 const (
 	// LarkCliService is the unified keychain service name for all secrets
 	// (both AppSecret and UAT). Entries are distinguished by account key format:
@@ -13,6 +28,28 @@ const (
 	LarkCliService = "lark-cli"
 )
 
+// wrapError is a helper to wrap underlying errors into output.ExitError.
+// It formats the error message and provides a hint for troubleshooting keychain access issues.
+func wrapError(op string, err error) error {
+	if err == nil || errors.Is(err, ErrNotFound) {
+		return err
+	}
+
+	msg := fmt.Sprintf("keychain %s failed: %v", op, err)
+	hint := "Check if the OS keychain/credential manager is locked or accessible. If running inside a sandbox or CI environment, please ensure the process has the necessary permissions to access the keychain."
+
+	if errors.Is(err, errNotInitialized) {
+		hint = "The keychain master key may have been cleaned up or deleted. Please reconfigure the CLI by running `lark-cli config init`."
+	}
+
+	func() {
+		defer func() { recover() }()
+		LogAuthError("keychain", op, fmt.Errorf("keychain %s error: %w", op, err))
+	}()
+
+	return output.ErrWithHint(output.ExitAPI, "config", msg, hint)
+}
+
 // KeychainAccess abstracts keychain Get/Set/Remove for dependency injection.
 // Used by AppSecret operations (ForStorage, ResolveSecretInput, RemoveSecretStore).
 // UAT operations in token_store.go use the package-level Get/Set/Remove directly.
@@ -24,16 +61,17 @@ type KeychainAccess interface {
 
 // Get retrieves a value from the keychain.
 // Returns empty string if the entry does not exist.
-func Get(service, account string) string {
-	return platformGet(service, account)
+func Get(service, account string) (string, error) {
+	val, err := platformGet(service, account)
+	return val, wrapError("Get", err)
 }
 
 // Set stores a value in the keychain, overwriting any existing entry.
 func Set(service, account, data string) error {
-	return platformSet(service, account, data)
+	return wrapError("Set", platformSet(service, account, data))
 }
 
 // Remove deletes an entry from the keychain. No error if not found.
 func Remove(service, account string) error {
-	return platformRemove(service, account)
+	return wrapError("Remove", platformRemove(service, account))
 }

internal/keychain/keychain_darwin.go

@@ -11,6 +11,7 @@ import (
 	"crypto/cipher"
 	"crypto/rand"
 	"encoding/base64"
+	"errors"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -36,11 +37,14 @@ func StorageDir(service string) string {
 
 var safeFileNameRe = regexp.MustCompile(`[^a-zA-Z0-9._-]`)
 
+// safeFileName sanitizes an account name to be used as a safe file name.
 func safeFileName(account string) string {
 	return safeFileNameRe.ReplaceAllString(account, "_") + ".enc"
 }
 
-func getMasterKey(service string) ([]byte, error) {
+// getMasterKey retrieves the master key from the system keychain.
+// If allowCreate is true, it generates and stores a new master key if one doesn't exist.
+func getMasterKey(service string, allowCreate bool) ([]byte, error) {
 	ctx, cancel := context.WithTimeout(context.Background(), keychainTimeout)
 	defer cancel()
 
@@ -59,28 +63,48 @@ func getMasterKey(service string) ([]byte, error) {
 				resCh <- result{key: key, err: nil}
 				return
 			}
+			// Key is found but invalid or corrupted
+			resCh <- result{key: nil, err: errors.New("keychain is corrupted")}
+			return
+		} else if !errors.Is(err, keyring.ErrNotFound) {
+			// Not ErrNotFound, which means access was denied or blocked by the system
+			resCh <- result{key: nil, err: errors.New("keychain access blocked")}
+			return
 		}
 
-		// Generate new master key if not found or invalid
+		// If ErrNotFound, check if we are allowed to create a new key
+		if !allowCreate {
+			// Creation not allowed (e.g., during Get operation), return error
+			resCh <- result{key: nil, err: errNotInitialized}
+			return
+		}
+
+		// It's the first time and creation is allowed (Set operation), generate a new key
 		key := make([]byte, masterKeyBytes)
 		if _, randErr := rand.Read(key); randErr != nil {
 			resCh <- result{key: nil, err: randErr}
 			return
 		}
 
-		encodedKey = base64.StdEncoding.EncodeToString(key)
-		setErr := keyring.Set(service, "master.key", encodedKey)
-		resCh <- result{key: key, err: setErr}
+		encodedKeyStr := base64.StdEncoding.EncodeToString(key)
+		setErr := keyring.Set(service, "master.key", encodedKeyStr)
+		if setErr != nil {
+			resCh <- result{key: nil, err: setErr}
+			return
+		}
+		resCh <- result{key: key, err: nil}
 	}()
 
 	select {
 	case res := <-resCh:
 		return res.key, res.err
 	case <-ctx.Done():
-		return nil, ctx.Err()
+		// Timeout is usually caused by ignored/blocked permission prompts
+		return nil, errors.New("keychain access blocked")
 	}
 }
 
+// encryptData encrypts data using AES-GCM.
 func encryptData(plaintext string, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {
@@ -103,6 +127,7 @@ func encryptData(plaintext string, key []byte) ([]byte, error) {
 	return result, nil
 }
 
+// decryptData decrypts data using AES-GCM.
 func decryptData(data []byte, key []byte) (string, error) {
 	if len(data) < ivBytes+tagBytes {
 		return "", os.ErrInvalid
@@ -125,24 +150,30 @@ func decryptData(data []byte, key []byte) (string, error) {
 	return string(plaintext), nil
 }
 
-func platformGet(service, account string) string {
-	key, err := getMasterKey(service)
-	if err != nil {
-		return ""
+// platformGet retrieves a value from the macOS keychain.
+func platformGet(service, account string) (string, error) {
+	path := filepath.Join(StorageDir(service), safeFileName(account))
+	data, err := os.ReadFile(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return "", nil
 	}
-	data, err := os.ReadFile(filepath.Join(StorageDir(service), safeFileName(account)))
 	if err != nil {
-		return ""
+		return "", err
+	}
+	key, err := getMasterKey(service, false)
+	if err != nil {
+		return "", err
 	}
 	plaintext, err := decryptData(data, key)
 	if err != nil {
-		return ""
+		return "", err
 	}
-	return plaintext
+	return plaintext, nil
 }
 
+// platformSet stores a value in the macOS keychain.
 func platformSet(service, account, data string) error {
-	key, err := getMasterKey(service)
+	key, err := getMasterKey(service, true)
 	if err != nil {
 		return err
 	}
@@ -170,6 +201,7 @@ func platformSet(service, account, data string) error {
 	return nil
 }
 
+// platformRemove deletes a value from the macOS keychain.
 func platformRemove(service, account string) error {
 	err := os.Remove(filepath.Join(StorageDir(service), safeFileName(account)))
 	if err != nil && !os.IsNotExist(err) {

internal/keychain/keychain_other.go

@@ -9,6 +9,7 @@ import (
 	"crypto/aes"
 	"crypto/cipher"
 	"crypto/rand"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -21,8 +22,7 @@ const masterKeyBytes = 32
 const ivBytes = 12
 const tagBytes = 16
 
-// StorageDir returns the storage directory for a given service name.
-// Each service gets its own directory for physical isolation.
+// StorageDir returns the directory where encrypted files are stored.
 func StorageDir(service string) string {
 	home, err := os.UserHomeDir()
 	if err != nil || home == "" {
@@ -36,11 +36,14 @@ func StorageDir(service string) string {
 
 var safeFileNameRe = regexp.MustCompile(`[^a-zA-Z0-9._-]`)
 
+// safeFileName sanitizes an account name to be used as a safe file name.
 func safeFileName(account string) string {
 	return safeFileNameRe.ReplaceAllString(account, "_") + ".enc"
 }
 
-func getMasterKey(service string) ([]byte, error) {
+// getMasterKey retrieves the master key from the file system.
+// If allowCreate is true, it generates and stores a new master key if one doesn't exist.
+func getMasterKey(service string, allowCreate bool) ([]byte, error) {
 	dir := StorageDir(service)
 	keyPath := filepath.Join(dir, "master.key")
 
@@ -48,6 +51,18 @@ func getMasterKey(service string) ([]byte, error) {
 	if err == nil && len(key) == masterKeyBytes {
 		return key, nil
 	}
+	if err == nil && len(key) != masterKeyBytes {
+		// Key file exists but is corrupted
+		return nil, errors.New("keychain is corrupted")
+	}
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		// Real I/O error (permission denied, etc.) - propagate it
+		return nil, err
+	}
+
+	if !allowCreate {
+		return nil, errNotInitialized
+	}
 
 	if err := os.MkdirAll(dir, 0700); err != nil {
 		return nil, err
@@ -78,6 +93,7 @@ func getMasterKey(service string) ([]byte, error) {
 	return key, nil
 }
 
+// encryptData encrypts data using AES-GCM.
 func encryptData(plaintext string, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {
@@ -100,6 +116,7 @@ func encryptData(plaintext string, key []byte) ([]byte, error) {
 	return result, nil
 }
 
+// decryptData decrypts data using AES-GCM.
 func decryptData(data []byte, key []byte) (string, error) {
 	if len(data) < ivBytes+tagBytes {
 		return "", os.ErrInvalid
@@ -122,24 +139,30 @@ func decryptData(data []byte, key []byte) (string, error) {
 	return string(plaintext), nil
 }
 
-func platformGet(service, account string) string {
-	key, err := getMasterKey(service)
-	if err != nil {
-		return ""
+// platformGet retrieves a value from the file system.
+func platformGet(service, account string) (string, error) {
+	path := filepath.Join(StorageDir(service), safeFileName(account))
+	data, err := os.ReadFile(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return "", nil
 	}
-	data, err := os.ReadFile(filepath.Join(StorageDir(service), safeFileName(account)))
 	if err != nil {
-		return ""
+		return "", err
+	}
+	key, err := getMasterKey(service, false)
+	if err != nil {
+		return "", err
 	}
 	plaintext, err := decryptData(data, key)
 	if err != nil {
-		return ""
+		return "", err
 	}
-	return plaintext
+	return plaintext, nil
 }
 
+// platformSet stores a value in the file system.
 func platformSet(service, account, data string) error {
-	key, err := getMasterKey(service)
+	key, err := getMasterKey(service, true)
 	if err != nil {
 		return err
 	}
@@ -167,6 +190,7 @@ func platformSet(service, account, data string) error {
 	return nil
 }
 
+// platformRemove deletes a value from the file system.
 func platformRemove(service, account string) error {
 	err := os.Remove(filepath.Join(StorageDir(service), safeFileName(account)))
 	if err != nil && !os.IsNotExist(err) {

internal/keychain/keychain_windows.go

@@ -22,12 +22,14 @@ import (
 
 const regRootPath = `Software\LarkCli\keychain`
 
+// registryPathForService returns the registry path for a given service.
 func registryPathForService(service string) string {
 	return regRootPath + `\` + safeRegistryComponent(service)
 }
 
 var safeRegRe = regexp.MustCompile(`[^a-zA-Z0-9._-]`)
 
+// safeRegistryComponent sanitizes a string to be used as a registry key component.
 func safeRegistryComponent(s string) string {
 	// Registry key path uses '\\' separators; avoid accidental nesting and odd chars.
 	s = strings.ReplaceAll(s, "\\", "_")
@@ -39,6 +41,7 @@ func valueNameForAccount(account string) string {
 	return base64.RawURLEncoding.EncodeToString([]byte(account))
 }
 
+// dpapiEntropy generates entropy for DPAPI encryption based on the service and account names.
 func dpapiEntropy(service, account string) *windows.DataBlob {
 	// Bind ciphertext to (service, account) to reduce swap/replay risks.
 	// Note: empty entropy is allowed, but we intentionally use deterministic entropy.
@@ -49,6 +52,7 @@ func dpapiEntropy(service, account string) *windows.DataBlob {
 	return &windows.DataBlob{Size: uint32(len(data)), Data: &data[0]}
 }
 
+// dpapiProtect encrypts data using Windows DPAPI.
 func dpapiProtect(plaintext []byte, entropy *windows.DataBlob) ([]byte, error) {
 	var in windows.DataBlob
 	if len(plaintext) > 0 {
@@ -70,6 +74,7 @@ func dpapiProtect(plaintext []byte, entropy *windows.DataBlob) ([]byte, error) {
 	return res, nil
 }
 
+// dpapiUnprotect decrypts data using Windows DPAPI.
 func dpapiUnprotect(ciphertext []byte, entropy *windows.DataBlob) ([]byte, error) {
 	var in windows.DataBlob
 	if len(ciphertext) > 0 {
@@ -91,6 +96,7 @@ func dpapiUnprotect(ciphertext []byte, entropy *windows.DataBlob) ([]byte, error
 	return res, nil
 }
 
+// freeDataBlob frees the memory allocated for a DataBlob.
 func freeDataBlob(b *windows.DataBlob) {
 	if b == nil || b.Data == nil {
 		return
@@ -101,11 +107,16 @@ func freeDataBlob(b *windows.DataBlob) {
 	b.Size = 0
 }
 
-func platformGet(service, account string) string {
-	v, _ := registryGet(service, account)
-	return v
+// platformGet retrieves a value from the Windows registry.
+func platformGet(service, account string) (string, error) {
+	v, ok := registryGet(service, account)
+	if !ok {
+		return "", nil
+	}
+	return v, nil
 }
 
+// platformSet stores a value in the Windows registry.
 func platformSet(service, account, data string) error {
 	entropy := dpapiEntropy(service, account)
 	protected, err := dpapiProtect([]byte(data), entropy)
@@ -115,10 +126,12 @@ func platformSet(service, account, data string) error {
 	return registrySet(service, account, protected)
 }
 
+// platformRemove deletes a value from the Windows registry.
 func platformRemove(service, account string) error {
 	return registryRemove(service, account)
 }
 
+// registryGet retrieves a string value from the registry under the given service and account.
 func registryGet(service, account string) (string, bool) {
 	keyPath := registryPathForService(service)
 	k, err := registry.OpenKey(registry.CURRENT_USER, keyPath, registry.QUERY_VALUE)
@@ -143,6 +156,7 @@ func registryGet(service, account string) (string, bool) {
 	return string(plain), true
 }
 
+// registrySet stores a string value in the registry under the given service and account.
 func registrySet(service, account string, protected []byte) error {
 	keyPath := registryPathForService(service)
 	k, _, err := registry.CreateKey(registry.CURRENT_USER, keyPath, registry.SET_VALUE)
@@ -158,6 +172,7 @@ func registrySet(service, account string, protected []byte) error {
 	return nil
 }
 
+// registryRemove deletes a value from the registry under the given service and account.
 func registryRemove(service, account string) error {
 	keyPath := registryPathForService(service)
 	k, err := registry.OpenKey(registry.CURRENT_USER, keyPath, registry.SET_VALUE)

internal/output/envelope.go

@@ -5,18 +5,20 @@ package output
 
 // Envelope is the standard success response wrapper.
 type Envelope struct {
-	OK       bool        `json:"ok"`
-	Identity string      `json:"identity,omitempty"`
-	Data     interface{} `json:"data,omitempty"`
-	Meta     *Meta       `json:"meta,omitempty"`
+	OK       bool                   `json:"ok"`
+	Identity string                 `json:"identity,omitempty"`
+	Data     interface{}            `json:"data,omitempty"`
+	Meta     *Meta                  `json:"meta,omitempty"`
+	Notice   map[string]interface{} `json:"_notice,omitempty"`
 }
 
 // ErrorEnvelope is the standard error response wrapper.
 type ErrorEnvelope struct {
-	OK       bool       `json:"ok"`
-	Identity string     `json:"identity,omitempty"`
-	Error    *ErrDetail `json:"error"`
-	Meta     *Meta      `json:"meta,omitempty"`
+	OK       bool                   `json:"ok"`
+	Identity string                 `json:"identity,omitempty"`
+	Error    *ErrDetail             `json:"error"`
+	Meta     *Meta                  `json:"meta,omitempty"`
+	Notice   map[string]interface{} `json:"_notice,omitempty"`
 }
 
 // ErrDetail describes a structured error.
@@ -34,3 +36,17 @@ type Meta struct {
 	Count    int    `json:"count,omitempty"`
 	Rollback string `json:"rollback,omitempty"`
 }
+
+// PendingNotice, if set, returns system-level notices to inject as the
+// "_notice" field in JSON output envelopes. Set by cmd/root.go.
+// Returns nil when there is nothing to report.
+var PendingNotice func() map[string]interface{}
+
+// GetNotice returns the current pending notice for struct-based callers.
+// Returns nil when there is nothing to report.
+func GetNotice() map[string]interface{} {
+	if PendingNotice == nil {
+		return nil
+	}
+	return PendingNotice()
+}

internal/output/errors.go

@@ -40,10 +40,11 @@ func WriteErrorEnvelope(w io.Writer, err *ExitError, identity string) {
 	if err.Detail == nil {
 		return
 	}
-	env := ErrorEnvelope{
+	env := &ErrorEnvelope{
 		OK:       false,
 		Identity: identity,
 		Error:    err.Detail,
+		Notice:   GetNotice(),
 	}
 	var buf bytes.Buffer
 	enc := json.NewEncoder(&buf)

internal/output/errors_test.go

@@ -4,6 +4,8 @@
 package output
 
 import (
+	"bytes"
+	"encoding/json"
 	"fmt"
 	"testing"
 )
@@ -37,3 +39,112 @@ func TestMarkRaw_Nil(t *testing.T) {
 		t.Error("expected MarkRaw(nil) to return nil")
 	}
 }
+
+func TestWriteErrorEnvelope_WithNotice(t *testing.T) {
+	// Set up PendingNotice
+	origNotice := PendingNotice
+	PendingNotice = func() map[string]interface{} {
+		return map[string]interface{}{
+			"update": map[string]interface{}{
+				"current": "1.0.0",
+				"latest":  "2.0.0",
+			},
+		}
+	}
+	defer func() { PendingNotice = origNotice }()
+
+	exitErr := &ExitError{
+		Code:   1,
+		Detail: &ErrDetail{Type: "api_error", Message: "something failed"},
+	}
+
+	var buf bytes.Buffer
+	WriteErrorEnvelope(&buf, exitErr, "user")
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+
+	// Verify _notice is present
+	notice, ok := env["_notice"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected _notice field in output")
+	}
+	update, ok := notice["update"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected _notice.update field")
+	}
+	if update["latest"] != "2.0.0" {
+		t.Errorf("expected latest=2.0.0, got %v", update["latest"])
+	}
+
+	// Verify standard fields
+	if env["ok"] != false {
+		t.Error("expected ok=false")
+	}
+	if env["identity"] != "user" {
+		t.Errorf("expected identity=user, got %v", env["identity"])
+	}
+}
+
+func TestWriteErrorEnvelope_WithoutNotice(t *testing.T) {
+	// Ensure PendingNotice is nil
+	origNotice := PendingNotice
+	PendingNotice = nil
+	defer func() { PendingNotice = origNotice }()
+
+	exitErr := &ExitError{
+		Code:   1,
+		Detail: &ErrDetail{Type: "api_error", Message: "something failed"},
+	}
+
+	var buf bytes.Buffer
+	WriteErrorEnvelope(&buf, exitErr, "bot")
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+
+	if _, ok := env["_notice"]; ok {
+		t.Error("expected no _notice field when PendingNotice is nil")
+	}
+}
+
+func TestWriteErrorEnvelope_NilDetail(t *testing.T) {
+	exitErr := &ExitError{Code: 1}
+
+	var buf bytes.Buffer
+	WriteErrorEnvelope(&buf, exitErr, "user")
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no output for nil Detail, got: %s", buf.String())
+	}
+}
+
+func TestGetNotice(t *testing.T) {
+	// Nil PendingNotice → nil
+	origNotice := PendingNotice
+	PendingNotice = nil
+	if got := GetNotice(); got != nil {
+		t.Errorf("expected nil, got %v", got)
+	}
+
+	// With PendingNotice → returns value
+	PendingNotice = func() map[string]interface{} {
+		return map[string]interface{}{"update": "test"}
+	}
+	got := GetNotice()
+	if got == nil || got["update"] != "test" {
+		t.Errorf("expected {update: test}, got %v", got)
+	}
+
+	// PendingNotice returns nil → nil
+	PendingNotice = func() map[string]interface{} { return nil }
+	if got := GetNotice(); got != nil {
+		t.Errorf("expected nil, got %v", got)
+	}
+
+	PendingNotice = origNotice
+}

internal/output/jq.go

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+
+	"github.com/itchyny/gojq"
+)
+
+// JqFilter applies a jq expression to data and writes the results to w.
+// Scalar values are printed raw (no quotes for strings), matching jq -r behavior.
+// Complex values (maps, arrays) are printed as indented JSON.
+func JqFilter(w io.Writer, data interface{}, expr string) error {
+	query, err := gojq.Parse(expr)
+	if err != nil {
+		return ErrValidation("invalid jq expression: %s", err)
+	}
+	code, err := gojq.Compile(query)
+	if err != nil {
+		return ErrValidation("invalid jq expression: %s", err)
+	}
+
+	// Normalize data through toGeneric so typed structs become map[string]any.
+	normalized := toGeneric(data)
+	// Convert json.Number values to gojq-compatible types.
+	normalized = convertNumbers(normalized)
+
+	iter := code.Run(normalized)
+	for {
+		v, ok := iter.Next()
+		if !ok {
+			break
+		}
+		if err, isErr := v.(error); isErr {
+			return Errorf(ExitAPI, "jq_error", "jq error: %s", err)
+		}
+		if err := writeJqValue(w, v); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ValidateJqFlags checks --jq flag compatibility with --output and --format flags,
+// and validates the jq expression syntax. Returns nil if jqExpr is empty.
+func ValidateJqFlags(jqExpr, outputFlag, format string) error {
+	if jqExpr == "" {
+		return nil
+	}
+	if outputFlag != "" {
+		return ErrValidation("--jq and --output are mutually exclusive")
+	}
+	if format != "" && format != "json" {
+		return ErrValidation("--jq and --format %s are mutually exclusive", format)
+	}
+	return ValidateJqExpression(jqExpr)
+}
+
+// ValidateJqExpression checks whether a jq expression is syntactically valid.
+func ValidateJqExpression(expr string) error {
+	query, err := gojq.Parse(expr)
+	if err != nil {
+		return ErrValidation("invalid jq expression: %s", err)
+	}
+	_, err = gojq.Compile(query)
+	if err != nil {
+		return ErrValidation("invalid jq expression: %s", err)
+	}
+	return nil
+}
+
+// writeJqValue writes a single jq result value to w.
+// Scalars are printed raw; complex values as indented JSON.
+func writeJqValue(w io.Writer, v interface{}) error {
+	switch val := v.(type) {
+	case nil:
+		fmt.Fprintln(w, "null")
+	case bool:
+		fmt.Fprintln(w, val)
+	case int:
+		fmt.Fprintln(w, val)
+	case float64:
+		// Use %g to avoid trailing zeros, matching jq behavior.
+		fmt.Fprintf(w, "%g\n", val)
+	case *big.Int:
+		fmt.Fprintln(w, val.String())
+	case string:
+		// Raw output for strings (no quotes), matching jq -r.
+		fmt.Fprintln(w, val)
+	default:
+		// Complex value (map, array): indented JSON.
+		b, err := json.MarshalIndent(v, "", "  ")
+		if err != nil {
+			return Errorf(ExitInternal, "jq_error", "failed to marshal jq result: %s", err)
+		}
+		fmt.Fprintln(w, string(b))
+	}
+	return nil
+}
+
+// convertNumbers recursively converts json.Number values to int or float64
+// so that gojq can process them correctly.
+func convertNumbers(v interface{}) interface{} {
+	switch val := v.(type) {
+	case json.Number:
+		if i, err := val.Int64(); err == nil {
+			return int(i)
+		}
+		if f, err := val.Float64(); err == nil {
+			return f
+		}
+		// Fallback: return as string (shouldn't happen for valid JSON numbers).
+		return val.String()
+	case map[string]interface{}:
+		for k, elem := range val {
+			val[k] = convertNumbers(elem)
+		}
+		return val
+	case []interface{}:
+		for i, elem := range val {
+			val[i] = convertNumbers(elem)
+		}
+		return val
+	default:
+		return v
+	}
+}

internal/output/jq_test.go

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestJqFilter(t *testing.T) {
+	data := map[string]interface{}{
+		"ok":       true,
+		"identity": "user",
+		"data": map[string]interface{}{
+			"items": []interface{}{
+				map[string]interface{}{"name": "Alice", "age": 30},
+				map[string]interface{}{"name": "Bob", "age": 25},
+				map[string]interface{}{"name": "Charlie", "age": 35},
+			},
+			"total": 3,
+		},
+		"meta": map[string]interface{}{
+			"count": 3,
+		},
+	}
+
+	tests := []struct {
+		name    string
+		expr    string
+		want    string
+		wantErr bool
+	}{
+		{
+			name: "identity expression",
+			expr: ".",
+			want: `"ok"`,
+		},
+		{
+			name: "field access .ok",
+			expr: ".ok",
+			want: "true\n",
+		},
+		{
+			name: "string field raw output",
+			expr: ".identity",
+			want: "user\n",
+		},
+		{
+			name: "nested field access",
+			expr: ".data.total",
+			want: "3\n",
+		},
+		{
+			name: "meta count",
+			expr: ".meta.count",
+			want: "3\n",
+		},
+		{
+			name: "array iteration",
+			expr: ".data.items[].name",
+			want: "Alice\nBob\nCharlie\n",
+		},
+		{
+			name: "pipe and select",
+			expr: `.data.items[] | select(.age > 28) | .name`,
+			want: "Alice\nCharlie\n",
+		},
+		{
+			name: "length builtin",
+			expr: ".data.items | length",
+			want: "3\n",
+		},
+		{
+			name: "keys builtin",
+			expr: ".data | keys",
+			want: "[\n  \"items\",\n  \"total\"\n]\n",
+		},
+		{
+			name: "null for missing field",
+			expr: ".nonexistent",
+			want: "null\n",
+		},
+		{
+			name: "complex value output",
+			expr: ".data.items[0]",
+			want: "{\n  \"age\": 30,\n  \"name\": \"Alice\"\n}\n",
+		},
+		{
+			name:    "invalid expression",
+			expr:    "invalid[",
+			wantErr: true,
+		},
+		{
+			name: "multiple outputs",
+			expr: ".ok, .identity",
+			want: "true\nuser\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			err := JqFilter(&buf, data, tt.expr)
+			if tt.wantErr {
+				if err == nil {
+					t.Error("expected error, got nil")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if tt.name == "identity expression" {
+				// For identity, just verify it contains the key fields
+				if !strings.Contains(buf.String(), `"ok"`) {
+					t.Errorf("identity output missing 'ok' key")
+				}
+				return
+			}
+			if buf.String() != tt.want {
+				t.Errorf("got %q, want %q", buf.String(), tt.want)
+			}
+		})
+	}
+}
+
+func TestJqFilter_WithStruct(t *testing.T) {
+	// Test that toGeneric normalizes structs properly
+	type inner struct {
+		Name string `json:"name"`
+	}
+	data := struct {
+		OK   bool   `json:"ok"`
+		Item *inner `json:"item"`
+	}{
+		OK:   true,
+		Item: &inner{Name: "test"},
+	}
+
+	var buf bytes.Buffer
+	err := JqFilter(&buf, data, ".item.name")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := strings.TrimSpace(buf.String()); got != "test" {
+		t.Errorf("got %q, want %q", got, "test")
+	}
+}
+
+func TestValidateJqFlags(t *testing.T) {
+	tests := []struct {
+		name       string
+		jqExpr     string
+		outputFlag string
+		format     string
+		wantErr    string
+	}{
+		{name: "empty jq is noop", jqExpr: "", outputFlag: "file.json", format: "csv", wantErr: ""},
+		{name: "jq only", jqExpr: ".data", outputFlag: "", format: "", wantErr: ""},
+		{name: "jq with json format", jqExpr: ".data", outputFlag: "", format: "json", wantErr: ""},
+		{name: "jq and output conflict", jqExpr: ".data", outputFlag: "out.json", format: "", wantErr: "--jq and --output are mutually exclusive"},
+		{name: "jq and csv conflict", jqExpr: ".data", outputFlag: "", format: "csv", wantErr: "--jq and --format csv are mutually exclusive"},
+		{name: "jq and ndjson conflict", jqExpr: ".data", outputFlag: "", format: "ndjson", wantErr: "--jq and --format ndjson are mutually exclusive"},
+		{name: "invalid expression", jqExpr: "invalid[", outputFlag: "", format: "", wantErr: "invalid jq expression"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateJqFlags(tt.jqExpr, tt.outputFlag, tt.format)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Errorf("unexpected error: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Errorf("expected error containing %q, got nil", tt.wantErr)
+				return
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error %q does not contain %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestValidateJqExpression(t *testing.T) {
+	tests := []struct {
+		expr    string
+		wantErr bool
+	}{
+		{".", false},
+		{".data", false},
+		{".data.items[].name", false},
+		{`.data.items[] | select(.name == "Alice")`, false},
+		{"length", false},
+		{"keys", false},
+		{"invalid[", true},
+		{".foo | invalid_func", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.expr, func(t *testing.T) {
+			err := ValidateJqExpression(tt.expr)
+			if tt.wantErr && err == nil {
+				t.Error("expected error, got nil")
+			}
+			if !tt.wantErr && err != nil {
+				t.Errorf("unexpected error: %v", err)
+			}
+		})
+	}
+}

internal/output/print.go

@@ -14,6 +14,7 @@ import (
 
 // PrintJson prints data as formatted JSON to w.
 func PrintJson(w io.Writer, data interface{}) {
+	injectNotice(data)
 	b, err := json.MarshalIndent(data, "", "  ")
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "json marshal error: %v\n", err)
@@ -22,6 +23,31 @@ func PrintJson(w io.Writer, data interface{}) {
 	fmt.Fprintln(w, string(b))
 }
 
+// injectNotice adds a "_notice" field into CLI envelope maps.
+// Only modifies map[string]interface{} values that have an "ok" key
+// (e.g. doctor, auth, config commands that build map envelopes directly).
+//
+// Struct-based envelopes (Envelope, ErrorEnvelope) are NOT handled here —
+// callers must set the Notice field explicitly via GetNotice().
+// See: shortcuts/common/runner.go Out(), output/errors.go WriteErrorEnvelope().
+func injectNotice(data interface{}) {
+	if PendingNotice == nil {
+		return
+	}
+	m, ok := data.(map[string]interface{})
+	if !ok {
+		return
+	}
+	if _, isEnvelope := m["ok"]; !isEnvelope {
+		return
+	}
+	notice := PendingNotice()
+	if notice == nil {
+		return
+	}
+	m["_notice"] = notice
+}
+
 // PrintNdjson prints data as NDJSON (Newline Delimited JSON) to w.
 func PrintNdjson(w io.Writer, data interface{}) {
 	emit := func(item interface{}) {

internal/output/print_test.go

@@ -0,0 +1,101 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+)
+
+func TestPrintJson_InjectNotice_Map(t *testing.T) {
+	origNotice := PendingNotice
+	PendingNotice = func() map[string]interface{} {
+		return map[string]interface{}{"update": "available"}
+	}
+	defer func() { PendingNotice = origNotice }()
+
+	data := map[string]interface{}{"ok": true, "data": "test"}
+	var buf bytes.Buffer
+	PrintJson(&buf, data)
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("failed to parse: %v", err)
+	}
+	notice, ok := got["_notice"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected _notice in map-based envelope")
+	}
+	if notice["update"] != "available" {
+		t.Errorf("expected update=available, got %v", notice["update"])
+	}
+}
+
+func TestPrintJson_InjectNotice_SkipsNonEnvelope(t *testing.T) {
+	origNotice := PendingNotice
+	PendingNotice = func() map[string]interface{} {
+		return map[string]interface{}{"update": "available"}
+	}
+	defer func() { PendingNotice = origNotice }()
+
+	// Map without "ok" key should not get _notice
+	data := map[string]interface{}{"name": "test"}
+	var buf bytes.Buffer
+	PrintJson(&buf, data)
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("failed to parse: %v", err)
+	}
+	if _, ok := got["_notice"]; ok {
+		t.Error("expected no _notice for non-envelope map")
+	}
+}
+
+func TestPrintJson_Struct_PreservesNotice(t *testing.T) {
+	origNotice := PendingNotice
+	PendingNotice = nil // no global notice
+	defer func() { PendingNotice = origNotice }()
+
+	// Struct with Notice already set should preserve it
+	env := &Envelope{
+		OK:       true,
+		Identity: "user",
+		Data:     "hello",
+		Notice:   map[string]interface{}{"update": "set-by-caller"},
+	}
+	var buf bytes.Buffer
+	PrintJson(&buf, env)
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("failed to parse: %v", err)
+	}
+	notice, ok := got["_notice"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected _notice from struct field")
+	}
+	if notice["update"] != "set-by-caller" {
+		t.Errorf("expected update=set-by-caller, got %v", notice["update"])
+	}
+}
+
+func TestPrintJson_NoNotice(t *testing.T) {
+	origNotice := PendingNotice
+	PendingNotice = nil
+	defer func() { PendingNotice = origNotice }()
+
+	data := map[string]interface{}{"ok": true, "data": "test"}
+	var buf bytes.Buffer
+	PrintJson(&buf, data)
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("failed to parse: %v", err)
+	}
+	if _, ok := got["_notice"]; ok {
+		t.Error("expected no _notice when PendingNotice is nil")
+	}
+}

internal/registry/service_descriptions.json

@@ -1,7 +1,11 @@
 {
+  "approval": {
+    "en": { "title": "Approval", "description": "Approval instance, and task management" },
+    "zh": { "title": "审批", "description": "审批实例、审批任务管理" }
+  },
   "base": {
-    "en": { "title": "Base", "description": "Table, field, record, and view management" },
-    "zh": { "title": "多维表格", "description": "数据表、字段、记录、视图" }
+    "en": { "title": "Base", "description": "Table, field, record, view, dashboard, workflow, form, role & permission management" },
+    "zh": { "title": "多维表格", "description": "数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限管理" }
   },
   "calendar": {
     "en": { "title": "Calendar", "description": "Calendar, event, and attendee management" },

internal/update/update.go

@@ -0,0 +1,259 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package update
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+const (
+	registryURL  = "https://registry.npmjs.org/@larksuite/cli/latest"
+	cacheTTL     = 24 * time.Hour
+	fetchTimeout = 5 * time.Second
+	stateFile    = "update-state.json"
+	maxBody      = 256 << 10 // 256 KB
+
+)
+
+// UpdateInfo holds version update information.
+type UpdateInfo struct {
+	Current string `json:"current"`
+	Latest  string `json:"latest"`
+}
+
+// Message returns a concise update notification.
+func (u *UpdateInfo) Message() string {
+	return fmt.Sprintf("lark-cli %s available, current %s", u.Latest, u.Current)
+}
+
+// pending stores the latest update info for the current process.
+var pending atomic.Pointer[UpdateInfo]
+
+// SetPending stores the update info for consumption by output decorators.
+func SetPending(info *UpdateInfo) { pending.Store(info) }
+
+// GetPending returns the pending update info, or nil.
+func GetPending() *UpdateInfo { return pending.Load() }
+
+// DefaultClient is the HTTP client used for npm registry requests.
+// Override in tests with an httptest server client.
+var DefaultClient *http.Client
+
+func httpClient() *http.Client {
+	if DefaultClient != nil {
+		return DefaultClient
+	}
+	return &http.Client{
+		Timeout:   fetchTimeout,
+		Transport: util.NewBaseTransport(),
+	}
+}
+
+// updateState is persisted to disk for caching.
+type updateState struct {
+	LatestVersion string `json:"latest_version"`
+	CheckedAt     int64  `json:"checked_at"`
+}
+
+// CheckCached checks the local cache only (no network). Always fast.
+func CheckCached(currentVersion string) *UpdateInfo {
+	if shouldSkip(currentVersion) {
+		return nil
+	}
+	state, _ := loadState()
+	if state == nil || state.LatestVersion == "" {
+		return nil
+	}
+	if !IsNewer(state.LatestVersion, currentVersion) {
+		return nil
+	}
+	return &UpdateInfo{Current: currentVersion, Latest: state.LatestVersion}
+}
+
+// RefreshCache fetches the latest version from npm and updates the local cache.
+// No-op if the cache is still fresh (< 24h). Safe to call from a goroutine.
+func RefreshCache(currentVersion string) {
+	if shouldSkip(currentVersion) {
+		return
+	}
+	state, _ := loadState()
+	if state != nil && time.Since(time.Unix(state.CheckedAt, 0)) < cacheTTL {
+		return // cache is fresh
+	}
+	latest, err := fetchLatestVersion()
+	if err != nil {
+		return
+	}
+	_ = saveState(&updateState{
+		LatestVersion: latest,
+		CheckedAt:     time.Now().Unix(),
+	})
+}
+
+func shouldSkip(version string) bool {
+	if os.Getenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER") != "" {
+		return true
+	}
+	// Suppress in CI environments.
+	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
+		if os.Getenv(key) != "" {
+			return true
+		}
+	}
+	// No version info at all — can't compare.
+	if version == "DEV" || version == "dev" || version == "" {
+		return true
+	}
+	// Skip local dev builds (e.g. v1.0.0-12-g9b933f1-dirty from git describe).
+	// Only released versions (clean X.Y.Z) should check for updates.
+	if !isRelease(version) {
+		return true
+	}
+	return false
+}
+
+// isRelease returns true for published versions: clean semver (1.0.0)
+// and npm prerelease (1.0.0-beta.1, 1.0.0-rc.1).
+// Returns false for git describe dev builds (v1.0.0-12-g9b933f1-dirty).
+var gitDescribePattern = regexp.MustCompile(`-\d+-g[0-9a-f]{7,}`)
+
+func isRelease(version string) bool {
+	v := strings.TrimPrefix(version, "v")
+	if ParseVersion(v) == nil {
+		return false
+	}
+	return !gitDescribePattern.MatchString(v)
+}
+
+// --- state file I/O ---
+
+func statePath() string {
+	return filepath.Join(core.GetConfigDir(), stateFile)
+}
+
+func loadState() (*updateState, error) {
+	data, err := os.ReadFile(statePath())
+	if err != nil {
+		return nil, err
+	}
+	var s updateState
+	if err := json.Unmarshal(data, &s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+func saveState(s *updateState) error {
+	dir := core.GetConfigDir()
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return err
+	}
+	data, err := json.Marshal(s)
+	if err != nil {
+		return err
+	}
+	return validate.AtomicWrite(statePath(), data, 0644)
+}
+
+// FetchLatest queries the npm registry and returns the latest published version.
+// This is a synchronous call with timeout, intended for diagnostic commands (doctor).
+func FetchLatest() (string, error) {
+	return fetchLatestVersion()
+}
+
+// --- npm registry ---
+
+type npmLatestResponse struct {
+	Version string `json:"version"`
+}
+
+func fetchLatestVersion() (string, error) {
+	resp, err := httpClient().Get(registryURL)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("npm registry: HTTP %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, maxBody))
+	if err != nil {
+		return "", err
+	}
+
+	var result npmLatestResponse
+	if err := json.Unmarshal(body, &result); err != nil {
+		return "", err
+	}
+	if result.Version == "" {
+		return "", fmt.Errorf("npm registry: empty version")
+	}
+	return result.Version, nil
+}
+
+// --- semver helpers ---
+
+// IsNewer returns true if version a should be considered an update over b.
+//
+// When both parse as semver, standard comparison applies.
+// When b cannot be parsed (e.g. bare commit hash "9b933f1"), any valid a
+// is considered newer — an unparseable local version is assumed outdated.
+// When a cannot be parsed, returns false (can't confirm it's newer).
+func IsNewer(a, b string) bool {
+	ap := ParseVersion(a)
+	bp := ParseVersion(b)
+	if ap == nil {
+		return false // can't confirm remote is newer
+	}
+	if bp == nil {
+		return true // local version unparseable → assume outdated
+	}
+	for i := 0; i < 3; i++ {
+		if ap[i] > bp[i] {
+			return true
+		}
+		if ap[i] < bp[i] {
+			return false
+		}
+	}
+	return false
+}
+
+// ParseVersion parses "X.Y.Z" (with optional "v" prefix and pre-release suffix)
+// into [major, minor, patch]. Returns nil on invalid input.
+func ParseVersion(v string) []int {
+	v = strings.TrimPrefix(v, "v")
+	parts := strings.SplitN(v, ".", 3)
+	if len(parts) != 3 {
+		return nil
+	}
+	nums := make([]int, 3)
+	for i, p := range parts {
+		if idx := strings.IndexAny(p, "-+"); idx >= 0 {
+			p = p[:idx]
+		}
+		n, err := strconv.Atoi(p)
+		if err != nil {
+			return nil
+		}
+		nums[i] = n
+	}
+	return nums
+}

internal/update/update_test.go

@@ -0,0 +1,253 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package update
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// roundTripFunc adapts a function to http.RoundTripper.
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { return f(req) }
+
+// clearSkipEnv unsets all env vars that shouldSkip checks,
+// preventing the host environment (e.g. CI=true) from polluting test results.
+func clearSkipEnv(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{"LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "CI", "BUILD_NUMBER", "RUN_ID"} {
+		t.Setenv(key, "")
+		os.Unsetenv(key)
+	}
+}
+
+func mustParseURL(raw string) *url.URL {
+	u, err := url.Parse(raw)
+	if err != nil {
+		panic(err)
+	}
+	return u
+}
+
+func TestIsNewer(t *testing.T) {
+	tests := []struct {
+		a, b string
+		want bool
+	}{
+		{"1.1.0", "1.0.0", true},
+		{"1.0.0", "1.0.0", false},
+		{"1.0.0", "1.1.0", false},
+		{"2.0.0", "1.9.9", true},
+		{"1.0.1", "1.0.0", true},
+		{"v1.1.0", "1.0.0", true},
+		{"1.1.0", "v1.0.0", true},
+		{"0.0.1", "0.0.0", true},
+		{"DEV", "1.0.0", false},                     // unparseable remote → false
+		{"1.0.0", "DEV", true},                      // unparseable local → assume outdated
+		{"1.0.0", "9b933f1", true},                  // bare commit hash → assume outdated
+		{"", "1.0.0", false},                        // empty remote → false
+		{"1.1.0", "v1.0.0-12-g9b933f1-dirty", true}, // git describe: 1.1.0 > 1.0.0
+	}
+	for _, tt := range tests {
+		got := IsNewer(tt.a, tt.b)
+		if got != tt.want {
+			t.Errorf("IsNewer(%q, %q) = %v, want %v", tt.a, tt.b, got, tt.want)
+		}
+	}
+}
+
+func TestParseVersion(t *testing.T) {
+	tests := []struct {
+		input string
+		want  []int
+	}{
+		{"1.2.3", []int{1, 2, 3}},
+		{"v1.2.3", []int{1, 2, 3}},
+		{"0.0.1", []int{0, 0, 1}},
+		{"1.0.0-beta.1", []int{1, 0, 0}},
+		{"DEV", nil},
+		{"", nil},
+		{"1.2", nil},
+	}
+	for _, tt := range tests {
+		got := ParseVersion(tt.input)
+		if tt.want == nil {
+			if got != nil {
+				t.Errorf("ParseVersion(%q) = %v, want nil", tt.input, got)
+			}
+			continue
+		}
+		if got == nil || got[0] != tt.want[0] || got[1] != tt.want[1] || got[2] != tt.want[2] {
+			t.Errorf("ParseVersion(%q) = %v, want %v", tt.input, got, tt.want)
+		}
+	}
+}
+
+func TestShouldSkip(t *testing.T) {
+	tests := []struct {
+		name    string
+		version string
+		env     map[string]string
+		want    bool
+	}{
+		{"DEV", "DEV", nil, true},
+		{"dev_lower", "dev", nil, true},
+		{"empty", "", nil, true},
+		{"CI", "1.0.0", map[string]string{"CI": "true"}, true},
+		{"BUILD_NUMBER", "1.0.0", map[string]string{"BUILD_NUMBER": "42"}, true},
+		{"RUN_ID", "1.0.0", map[string]string{"RUN_ID": "123"}, true},
+		{"notifier_off", "1.0.0", map[string]string{"LARKSUITE_CLI_NO_UPDATE_NOTIFIER": "1"}, true},
+		{"git_describe", "v1.0.0-12-g9b933f1", nil, true},
+		{"git_dirty", "v1.0.0-12-g9b933f1-dirty", nil, true},
+		{"commit_hash", "9b933f1", nil, true},
+		{"clean_semver", "1.0.0", nil, false},
+		{"clean_semver_v", "v1.0.0", nil, false},
+		{"prerelease_beta", "1.0.0-beta.1", nil, false},
+		{"prerelease_rc", "2.0.0-rc.1", nil, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clearSkipEnv(t)
+			for k, v := range tt.env {
+				t.Setenv(k, v)
+			}
+			got := shouldSkip(tt.version)
+			if got != tt.want {
+				t.Errorf("shouldSkip(%q) = %v, want %v", tt.version, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsRelease(t *testing.T) {
+	tests := []struct {
+		version string
+		want    bool
+	}{
+		{"1.0.0", true},
+		{"v1.0.0", true},
+		{"0.1.0", true},
+		{"1.0.0-beta.1", true},
+		{"1.0.0-rc.1", true},
+		{"2.0.0-alpha.0", true},
+		{"v1.0.0-12-g9b933f1", false},       // git describe
+		{"v1.0.0-12-g9b933f1-dirty", false}, // git describe dirty
+		{"v2.1.0-3-gabcdef0", false},        // git describe short
+		{"9b933f1", false},                  // bare commit hash
+		{"DEV", false},                      // dev marker
+		{"", false},                         // empty
+		{"1.0", false},                      // incomplete semver
+	}
+	for _, tt := range tests {
+		t.Run(tt.version, func(t *testing.T) {
+			got := isRelease(tt.version)
+			if got != tt.want {
+				t.Errorf("isRelease(%q) = %v, want %v", tt.version, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUpdateInfoMethods(t *testing.T) {
+	info := &UpdateInfo{Current: "1.0.0", Latest: "2.0.0"}
+
+	msg := info.Message()
+	if !strings.Contains(msg, "2.0.0") {
+		t.Errorf("Message() missing latest version: %s", msg)
+	}
+	if !strings.Contains(msg, "1.0.0") {
+		t.Errorf("Message() missing current version: %s", msg)
+	}
+}
+
+func TestCheckCached(t *testing.T) {
+	clearSkipEnv(t)
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+
+	// No cache → nil
+	info := CheckCached("1.0.0")
+	if info != nil {
+		t.Errorf("expected nil with no cache, got %+v", info)
+	}
+
+	// Write cache with newer version
+	state := &updateState{LatestVersion: "2.0.0", CheckedAt: time.Now().Unix()}
+	data, _ := json.Marshal(state)
+	os.WriteFile(filepath.Join(tmp, stateFile), data, 0644)
+
+	info = CheckCached("1.0.0")
+	if info == nil {
+		t.Fatal("expected update info, got nil")
+	}
+	if info.Latest != "2.0.0" || info.Current != "1.0.0" {
+		t.Errorf("unexpected info: %+v", info)
+	}
+
+	// Same version → nil
+	info = CheckCached("2.0.0")
+	if info != nil {
+		t.Errorf("expected nil when versions match, got %+v", info)
+	}
+}
+
+func TestRefreshCache(t *testing.T) {
+	clearSkipEnv(t)
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+
+	// Set up mock npm registry via DefaultClient
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewEncoder(w).Encode(npmLatestResponse{Version: "3.0.0"})
+	}))
+	defer srv.Close()
+
+	// Redirect all requests to the mock server.
+	DefaultClient = srv.Client()
+	DefaultClient.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		req.URL = mustParseURL(srv.URL + req.URL.Path)
+		return http.DefaultTransport.RoundTrip(req)
+	})
+	defer func() { DefaultClient = nil }()
+
+	RefreshCache("1.0.0")
+
+	// Verify cache was written
+	info := CheckCached("1.0.0")
+	if info == nil {
+		t.Fatal("expected update info after refresh, got nil")
+	}
+	if info.Latest != "3.0.0" {
+		t.Errorf("expected latest 3.0.0, got %s", info.Latest)
+	}
+
+	// Second refresh should be no-op (cache is fresh) — won't hit network.
+	RefreshCache("1.0.0")
+}
+
+func TestPendingAtomicAccess(t *testing.T) {
+	// Initially nil
+	if got := GetPending(); got != nil {
+		t.Errorf("expected nil, got %+v", got)
+	}
+
+	info := &UpdateInfo{Current: "1.0.0", Latest: "2.0.0"}
+	SetPending(info)
+
+	got := GetPending()
+	if got == nil || got.Current != "1.0.0" || got.Latest != "2.0.0" {
+		t.Errorf("unexpected pending: %+v", got)
+	}
+
+	// Clean up for other tests
+	SetPending(nil)
+}

internal/util/proxy.go

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package util
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"sync"
+)
+
+const (
+	// EnvNoProxy disables automatic proxy support when set to any non-empty value.
+	EnvNoProxy = "LARK_CLI_NO_PROXY"
+)
+
+// proxyEnvKeys lists environment variables that Go's ProxyFromEnvironment reads.
+var proxyEnvKeys = []string{
+	"HTTPS_PROXY", "https_proxy",
+	"HTTP_PROXY", "http_proxy",
+	"ALL_PROXY", "all_proxy",
+}
+
+// DetectProxyEnv returns the first proxy-related environment variable that is set,
+// or empty strings if none are configured.
+func DetectProxyEnv() (key, value string) {
+	for _, k := range proxyEnvKeys {
+		if v := os.Getenv(k); v != "" {
+			return k, v
+		}
+	}
+	return "", ""
+}
+
+var proxyWarningOnce sync.Once
+
+// redactProxyURL masks userinfo (username:password) in a proxy URL.
+// Handles both scheme-prefixed ("http://user:pass@host") and bare ("user:pass@host") formats.
+func redactProxyURL(raw string) string {
+	// Try standard url.Parse first (works when scheme is present)
+	u, err := url.Parse(raw)
+	if err == nil && u.User != nil {
+		return u.Scheme + "://***@" + u.Host + u.RequestURI()
+	}
+
+	// Fallback: handle bare URLs without scheme (e.g. "user:pass@proxy:8080")
+	if at := strings.LastIndex(raw, "@"); at > 0 {
+		return "***@" + raw[at+1:]
+	}
+
+	return raw
+}
+
+// WarnIfProxied prints a one-time warning to w when a proxy environment variable
+// is detected and proxy is not disabled via LARK_CLI_NO_PROXY. Proxy credentials
+// are redacted. Safe to call multiple times; only the first call prints.
+func WarnIfProxied(w io.Writer) {
+	proxyWarningOnce.Do(func() {
+		if os.Getenv(EnvNoProxy) != "" {
+			return
+		}
+		key, val := DetectProxyEnv()
+		if key == "" {
+			return
+		}
+		fmt.Fprintf(w, "[lark-cli] [WARN] proxy detected: %s=%s — requests (including credentials) will transit through this proxy. Set %s=1 to disable proxy.\n",
+			key, redactProxyURL(val), EnvNoProxy)
+	})
+}
+
+// NewBaseTransport creates an *http.Transport cloned from http.DefaultTransport.
+// If LARK_CLI_NO_PROXY is set, proxy support is disabled.
+// Each call returns a new instance; use FallbackTransport for a shared singleton.
+func NewBaseTransport() *http.Transport {
+	def, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		return &http.Transport{}
+	}
+	t := def.Clone()
+	if os.Getenv(EnvNoProxy) != "" {
+		t.Proxy = nil
+	}
+	return t
+}
+
+// fallbackTransport is a lazily-initialized singleton used by transport
+// decorators when their Base field is nil, preserving connection pooling.
+var fallbackTransport = sync.OnceValue(func() *http.Transport {
+	return NewBaseTransport()
+})
+
+// FallbackTransport returns a shared *http.Transport singleton suitable for
+// use as a fallback when a transport decorator's Base is nil.
+// Unlike NewBaseTransport (which clones per call), this reuses a single
+// instance so that TCP connections and TLS sessions are pooled.
+func FallbackTransport() *http.Transport {
+	return fallbackTransport()
+}

internal/util/proxy_test.go

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package util
+
+import (
+	"bytes"
+	"net/http"
+	"sync"
+	"testing"
+)
+
+func TestDetectProxyEnv(t *testing.T) {
+	// Clear all proxy env vars first
+	for _, k := range proxyEnvKeys {
+		t.Setenv(k, "")
+	}
+
+	key, val := DetectProxyEnv()
+	if key != "" || val != "" {
+		t.Errorf("expected no proxy, got %s=%s", key, val)
+	}
+
+	t.Setenv("HTTPS_PROXY", "http://proxy:8888")
+	key, val = DetectProxyEnv()
+	if key != "HTTPS_PROXY" || val != "http://proxy:8888" {
+		t.Errorf("expected HTTPS_PROXY=http://proxy:8888, got %s=%s", key, val)
+	}
+}
+
+func TestNewBaseTransport_Default(t *testing.T) {
+	t.Setenv(EnvNoProxy, "")
+	tr := NewBaseTransport()
+	if tr.Proxy == nil {
+		t.Error("expected proxy func to be set when LARK_CLI_NO_PROXY is not set")
+	}
+}
+
+func TestNewBaseTransport_NoProxy(t *testing.T) {
+	t.Setenv(EnvNoProxy, "1")
+	tr := NewBaseTransport()
+	if tr.Proxy != nil {
+		t.Error("expected proxy func to be nil when LARK_CLI_NO_PROXY=1")
+	}
+}
+
+func TestWarnIfProxied_WithProxy(t *testing.T) {
+	// Reset the once guard for this test
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	out := buf.String()
+	if out == "" {
+		t.Error("expected warning output when proxy is set")
+	}
+	if !bytes.Contains([]byte(out), []byte("HTTPS_PROXY")) {
+		t.Errorf("warning should mention HTTPS_PROXY, got: %s", out)
+	}
+	if !bytes.Contains([]byte(out), []byte(EnvNoProxy)) {
+		t.Errorf("warning should mention %s, got: %s", EnvNoProxy, out)
+	}
+}
+
+func TestWarnIfProxied_WithoutProxy(t *testing.T) {
+	proxyWarningOnce = sync.Once{}
+
+	for _, k := range proxyEnvKeys {
+		t.Setenv(k, "")
+	}
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no output when no proxy is set, got: %s", buf.String())
+	}
+}
+
+func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://proxy:8080")
+	t.Setenv(EnvNoProxy, "1")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no warning when proxy is disabled, got: %s", buf.String())
+	}
+}
+
+func TestWarnIfProxied_OnlyOnce(t *testing.T) {
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTP_PROXY", "http://proxy:1234")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+	first := buf.String()
+
+	WarnIfProxied(&buf)
+	second := buf.String()
+
+	if first == "" {
+		t.Error("expected warning on first call")
+	}
+	if second != first {
+		t.Error("expected no additional output on second call")
+	}
+}
+
+func TestRedactProxyURL(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"http://proxy:8080", "http://proxy:8080"},
+		{"http://user:pass@proxy:8080", "http://***@proxy:8080/"},
+		{"http://user:p%40ss@proxy:8080/path", "http://***@proxy:8080/path"},
+		{"http://user@proxy:8080", "http://***@proxy:8080/"},
+		{"socks5://admin:secret@10.0.0.1:1080", "socks5://***@10.0.0.1:1080/"},
+		{"user:pass@proxy:8080", "***@proxy:8080"},
+		{"admin:s3cret@10.0.0.1:3128", "***@10.0.0.1:3128"},
+		{"not-a-url", "not-a-url"},
+		{"", ""},
+	}
+	for _, tt := range tests {
+		got := redactProxyURL(tt.input)
+		if got != tt.want {
+			t.Errorf("redactProxyURL(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+func TestWarnIfProxied_RedactsCredentials(t *testing.T) {
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://admin:s3cret@proxy:8080")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	out := buf.String()
+	if bytes.Contains([]byte(out), []byte("s3cret")) {
+		t.Errorf("warning should not contain proxy password, got: %s", out)
+	}
+	if bytes.Contains([]byte(out), []byte("admin")) {
+		t.Errorf("warning should not contain proxy username, got: %s", out)
+	}
+	if !bytes.Contains([]byte(out), []byte("***@proxy:8080")) {
+		t.Errorf("warning should contain redacted proxy URL, got: %s", out)
+	}
+}
+
+func TestNewBaseTransport_IsHTTPTransport(t *testing.T) {
+	t.Setenv(EnvNoProxy, "")
+	tr := NewBaseTransport()
+
+	// Should be a valid *http.Transport that can be used
+	var rt http.RoundTripper = tr
+	_ = rt
+
+	// Verify it's not the same pointer as DefaultTransport (should be a clone)
+	if tr == http.DefaultTransport {
+		t.Error("NewBaseTransport should return a clone, not DefaultTransport itself")
+	}
+}
+
+func TestNewBaseTransport_RespectsNoProxyEnv(t *testing.T) {
+	// Simulate: user sets both system proxy and our disable flag
+	t.Setenv("HTTPS_PROXY", "http://should-be-ignored:8888")
+	t.Setenv(EnvNoProxy, "1")
+
+	tr := NewBaseTransport()
+	if tr.Proxy != nil {
+		t.Error("LARK_CLI_NO_PROXY should override system proxy settings")
+	}
+
+	// Clean up and verify proxy is restored
+	t.Setenv(EnvNoProxy, "")
+	tr2 := NewBaseTransport()
+	if tr2.Proxy == nil {
+		t.Error("proxy should be enabled when LARK_CLI_NO_PROXY is unset")
+	}
+}

internal/validate/url.go

@@ -181,6 +181,25 @@ func cloneDownloadTransport(base http.RoundTripper) *http.Transport {
 	return cloned
 }
 
+// DialContextFunc is the signature for DialContext / DialTLSContext.
+type DialContextFunc func(ctx context.Context, network, addr string) (net.Conn, error)
+
+// WrapDialContextWithIPCheck wraps a DialContext function to validate the
+// remote IP after connection, rejecting local/internal addresses (SSRF protection).
+func WrapDialContextWithIPCheck(origDial DialContextFunc) DialContextFunc {
+	return func(ctx context.Context, network, addr string) (net.Conn, error) {
+		conn, err := dialConn(ctx, origDial, network, addr)
+		if err != nil {
+			return nil, err
+		}
+		if err := validateConnRemoteIP(conn); err != nil {
+			conn.Close()
+			return nil, err
+		}
+		return conn, nil
+	}
+}
+
 func dialConn(ctx context.Context, dialFn func(context.Context, string, string) (net.Conn, error), network, addr string) (net.Conn, error) {
 	if dialFn != nil {
 		return dialFn(ctx, network, addr)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

scripts/build-pkg-pr-new.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="$ROOT_DIR/.pkg-pr-new"
+
+cd "$ROOT_DIR"
+
+python3 scripts/fetch_meta.py
+
+rm -rf "$OUT_DIR"
+mkdir -p "$OUT_DIR/bin" "$OUT_DIR/scripts"
+
+VERSION="$(node -p "require('./package.json').version")"
+DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+SHA="$(git rev-parse --short HEAD)"
+LDFLAGS="-s -w -X github.com/larksuite/cli/internal/build.Version=${VERSION}-${SHA} -X github.com/larksuite/cli/internal/build.Date=${DATE}"
+
+build_target() {
+  local goos="$1"
+  local goarch="$2"
+  local ext=""
+  if [[ "$goos" == "windows" ]]; then
+    ext=".exe"
+  fi
+
+  local output="$OUT_DIR/bin/lark-cli-${goos}-${goarch}${ext}"
+  echo "Building ${goos}/${goarch} -> ${output}"
+  CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -trimpath -ldflags "$LDFLAGS" -o "$output" ./main.go
+}
+
+build_target darwin arm64
+build_target linux amd64
+build_target darwin amd64
+build_target linux arm64
+build_target windows amd64
+build_target windows arm64
+
+cat > "$OUT_DIR/scripts/run.js" <<'RUNJS'
+#!/usr/bin/env node
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const isWindows = process.platform === "win32";
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+// TODO: Keep broad platform mapping for now; with pkg.pr.new 20MB limit we only ship a subset of binaries.
+// Track upstream progress before tightening runtime handling: https://github.com/stackblitz-labs/pkg.pr.new/pull/484
+
+const archMap = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = platformMap[process.platform];
+const arch = archMap[process.arch];
+
+if (!platform || !arch) {
+  console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
+  process.exit(1);
+}
+
+const ext = isWindows ? ".exe" : "";
+const binary = path.join(__dirname, "..", "bin", `lark-cli-${platform}-${arch}${ext}`);
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status || 1);
+}
+RUNJS
+
+chmod +x "$OUT_DIR/scripts/run.js"
+
+cat > "$OUT_DIR/package.json" <<EOF_JSON
+{
+  "name": "@larksuite/cli",
+  "version": "${VERSION}-pr.${SHA}",
+  "description": "The official CLI for Lark/Feishu open platform (PR preview build)",
+  "bin": {
+    "lark-cli": "scripts/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/larksuite/cli.git"
+  },
+  "license": "MIT",
+  "files": [
+    "bin",
+    "scripts/run.js",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}
+EOF_JSON
+
+cp CHANGELOG.md "$OUT_DIR/CHANGELOG.md"
+cp LICENSE "$OUT_DIR/LICENSE"
+
+echo "Prepared pkg.pr.new package at $OUT_DIR"

scripts/fetch_meta.py

@@ -67,8 +67,24 @@ def main():
     parser = argparse.ArgumentParser(description="Fetch meta_data.json for build-time embedding")
     parser.add_argument("--brand", default="feishu", choices=["feishu", "lark"],
                         help="API brand (default: feishu)")
+    parser.add_argument("--force", action="store_true",
+                        help="force refresh from remote even if local file exists")
     args = parser.parse_args()
 
+    if os.path.exists(OUT_PATH) and not args.force:
+        if os.path.isfile(OUT_PATH):
+            try:
+                with open(OUT_PATH, "r", encoding="utf-8") as fp:
+                    local = json.load(fp)
+                if local.get("services"):
+                    print(f"fetch-meta: {OUT_PATH} already exists, skipping (use --force to re-fetch)", file=sys.stderr)
+                    return
+                print(f"fetch-meta: {OUT_PATH} has no services, re-fetching", file=sys.stderr)
+            except (OSError, json.JSONDecodeError):
+                print(f"fetch-meta: {OUT_PATH} is invalid JSON, re-fetching", file=sys.stderr)
+        else:
+            print(f"fetch-meta: {OUT_PATH} is not a file, re-fetching", file=sys.stderr)
+
     data = fetch_remote(args.brand)
     count = len(data.get("services", []))
     print(f"fetch-meta: OK, {count} services from remote API", file=sys.stderr)

scripts/install.js

@@ -1,6 +1,5 @@
 const fs = require("fs");
 const path = require("path");
-const https = require("https");
 const { execSync } = require("child_process");
 const os = require("os");
 
@@ -32,45 +31,34 @@ if (!platform || !arch) {
 const isWindows = process.platform === "win32";
 const ext = isWindows ? ".zip" : ".tar.gz";
 const archiveName = `${NAME}-${VERSION}-${platform}-${arch}${ext}`;
-const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+const GITHUB_URL = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+const MIRROR_URL = `https://registry.npmmirror.com/-/binary/lark-cli/v${VERSION}/${archiveName}`;
+
 const binDir = path.join(__dirname, "..", "bin");
 const dest = path.join(binDir, NAME + (isWindows ? ".exe" : ""));
 
 fs.mkdirSync(binDir, { recursive: true });
 
 function download(url, destPath) {
-  return new Promise((resolve, reject) => {
-    const client = url.startsWith("https") ? https : require("http");
-    client
-      .get(url, (res) => {
-        if (res.statusCode === 302 || res.statusCode === 301) {
-          return download(res.headers.location, destPath).then(
-            resolve,
-            reject
-          );
-        }
-        if (res.statusCode !== 200) {
-          return reject(
-            new Error(`Download failed with status ${res.statusCode}: ${url}`)
-          );
-        }
-        const file = fs.createWriteStream(destPath);
-        res.pipe(file);
-        file.on("finish", () => {
-          file.close();
-          resolve();
-        });
-      })
-      .on("error", reject);
-  });
+  // --ssl-revoke-best-effort: on Windows (Schannel), avoid CRYPT_E_REVOCATION_OFFLINE
+  // errors when the certificate revocation list server is unreachable
+  const sslFlag = isWindows ? "--ssl-revoke-best-effort " : "";
+  execSync(
+    `curl ${sslFlag}--fail --location --silent --show-error --connect-timeout 10 --max-time 120 --output "${destPath}" "${url}"`,
+    { stdio: ["ignore", "ignore", "pipe"] }
+  );
 }
 
-async function install() {
+function install() {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lark-cli-"));
   const archivePath = path.join(tmpDir, archiveName);
 
   try {
-    await download(url, archivePath);
+    try {
+      download(GITHUB_URL, archivePath);
+    } catch (err) {
+      download(MIRROR_URL, archivePath);
+    }
 
     if (isWindows) {
       execSync(
@@ -94,7 +82,14 @@ async function install() {
   }
 }
 
-install().catch((err) => {
+try {
+  install();
+} catch (err) {
   console.error(`Failed to install ${NAME}:`, err.message);
+  console.error(
+    `\nIf you are behind a firewall or in a restricted network, try setting a proxy:\n` +
+    `  export https_proxy=http://your-proxy:port\n` +
+    `  npm install -g @larksuite/cli`
+  );
   process.exit(1);
-});
+}

scripts/pr-labels/README.md

@@ -0,0 +1,58 @@
+# PR Label Sync
+
+This directory contains scripts and sample data for automatically classifying and labeling GitHub Pull Requests based on the files they modify.
+
+## Files
+
+- `index.js`: The main Node.js script. It fetches PR files, evaluates their risk level, calculates business impact, and uses GitHub APIs to add appropriate `size/*` and `domain/*` labels.
+- `samples.json`: A collection of historical PRs used as test cases to verify the labeling logic (especially for regression testing the S/M/L thresholds).
+
+## Features
+
+### Size Labels (`size/*`)
+The script evaluates the "effective" lines of code changed (ignoring tests, docs, and ci files) to classify the PR:
+- **`size/S`**: Low-risk changes involving only docs, tests, CI workflows, or chores.
+- **`size/M`**: Small-to-medium changes affecting a single business domain, with effective lines under 300.
+- **`size/L`**: Large features (>= 300 lines), cross-domain changes, or any changes touching core architecture paths (like `cmd/`).
+- **`size/XL`**: Architectural overhauls, extremely large PRs (>1200 lines), or sensitive refactors.
+
+### Domain Tags (`domain/*`)
+The script also identifies which business domains a PR touches to give reviewers an immediate sense of the impact scope. Currently tracked domains include:
+- `domain/im`
+- `domain/vc`
+- `domain/ccm`
+- `domain/base`
+- `domain/mail`
+- `domain/calendar`
+- `domain/task`
+- `domain/contact`
+
+Minor modules like docs and tests are omitted to keep PR tags clean and focused on structural changes.
+
+## Usage
+
+### In GitHub Actions
+This script is designed to run in CI workflows. It automatically reads the `GITHUB_EVENT_PATH` payload to get the PR context.
+
+```bash
+node scripts/pr-labels/index.js
+```
+
+### Local Dry Run
+You can test the labeling logic against an existing GitHub PR without actually applying labels by using the `--dry-run` flag.
+
+```bash
+# Requires GITHUB_TOKEN environment variable or passing --token
+node scripts/pr-labels/index.js --dry-run --repo larksuite/cli --pr-number 123
+```
+
+## Testing
+
+A regression test suite is available in `test.js` which verifies the output of the classification logic against historical PRs configured in `samples.json`.
+
+```bash
+# Requires GITHUB_TOKEN environment variable to avoid rate limits
+GITHUB_TOKEN=$(gh auth token) node scripts/pr-labels/test.js
+```
+
+This test suite also runs automatically in CI via `.github/workflows/pr-labels-test.yml` when changes are made to this directory.

scripts/pr-labels/index.js

@@ -0,0 +1,747 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+// ============================================================================
+// Constants & Configuration
+// ============================================================================
+
+const API_BASE = "https://api.github.com";
+const SCRIPT_DIR = __dirname;
+const ROOT = path.join(SCRIPT_DIR, "..", "..");
+
+const THRESHOLD_L = 300;
+const THRESHOLD_XL = 1200;
+
+const LABEL_DEFINITIONS = {
+  "size/S": { color: "77bb00", description: "Low-risk docs, CI, test, or chore only changes" },
+  "size/M": { color: "eebb00", description: "Single-domain feat or fix with limited business impact" },
+  "size/L": { color: "ff8800", description: "Large or sensitive change across domains or core paths" },
+  "size/XL": { color: "ee0000", description: "Architecture-level or global-impact change" },
+};
+
+const MANAGED_LABELS = new Set(Object.keys(LABEL_DEFINITIONS));
+
+// File path matching configurations
+const DOC_SUFFIXES = [".md", ".mdx", ".txt", ".rst"];
+const LOW_RISK_PREFIXES = [".github/", "docs/", ".changeset/", "testdata/", "tests/", "skill-template/"];
+const LOW_RISK_FILENAMES = new Set(["readme.md", "readme.zh.md", "changelog.md", "license", "cla.md"]);
+const LOW_RISK_TEST_SUFFIXES = ["_test.go", ".snap"];
+
+const CORE_PREFIXES = ["internal/auth/", "internal/engine/", "internal/config/", "cmd/"];
+const HEAD_BUSINESS_DOMAINS = new Set(["im", "contact", "ccm", "base", "docx"]);
+const LOW_RISK_TYPES = new Set(["docs", "ci", "test", "chore"]);
+
+// CODEOWNERS-based path to domain label mapping
+// Maps shortcuts and skills paths to business domain labels
+const PATH_TO_DOMAIN_MAP = {
+  // shortcuts
+  "shortcuts/im/": "im",
+  "shortcuts/vc/": "vc",
+  "shortcuts/calendar/": "calendar",
+  "shortcuts/doc/": "ccm",
+  "shortcuts/sheets/": "ccm",
+  "shortcuts/drive/": "ccm",
+  "shortcuts/base/": "base",
+  "shortcuts/mail/": "mail",
+  "shortcuts/task/": "task",
+  "shortcuts/contact/": "contact",
+  // skills
+  "skills/lark-im/": "im",
+  "skills/lark-vc/": "vc",
+  "skills/lark-doc/": "ccm",
+  "skills/lark-base/": "base",
+  "skills/lark-mail/": "mail",
+  "skills/lark-calendar/": "calendar",
+  "skills/lark-task/": "task",
+  "skills/lark-contact/": "contact",
+};
+
+const SENSITIVE_PATTERN = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;
+
+const CLASS_STANDARDS = {
+  "size/S": {
+    channel: "Fast track (S)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+    ],
+  },
+  "size/M": {
+    channel: "Fast track (M)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+    ],
+  },
+  "size/L": {
+    channel: "Standard track (L)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+      "Domain evaluation passed: reported success rate is greater than 95%",
+    ],
+  },
+  "size/XL": {
+    channel: "Strict track (XL)",
+    gates: [
+      "Code quality: AI code review passed",
+      "Dependency and configuration security checks passed",
+      "Skill format validation: added or modified Skills load successfully",
+      "CLI automation tests: all required business-line tests passed",
+      "Domain evaluation passed: reported success rate is greater than 95%",
+      "Cross-domain release gate: all domains and full integration evaluations passed",
+    ],
+  },
+};
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function log(message) {
+  console.error(`sync-pr-labels: ${message}`);
+}
+
+function normalizePath(input) {
+  return String(input || "").trim().toLowerCase();
+}
+
+function envValue(name) {
+  return (process.env[name] || "").trim();
+}
+
+function envOrFail(name) {
+  const value = envValue(name);
+  if (!value) {
+    throw new Error(`missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+// ============================================================================
+// GitHub API Client
+// ============================================================================
+
+class GitHubClient {
+  constructor(token, repo, prNumber) {
+    this.token = token;
+    this.repo = repo;
+    this.prNumber = prNumber;
+  }
+
+  buildHeaders(hasBody = false) {
+    const headers = {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+    };
+    if (this.token) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+    if (hasBody) {
+      headers["Content-Type"] = "application/json";
+    }
+    return headers;
+  }
+
+  async request(endpoint, options = {}) {
+    const { method = "GET", payload, allow404 = false } = options;
+    const hasBody = payload !== undefined;
+    const url = endpoint.startsWith("http") ? endpoint : `${API_BASE}${endpoint}`;
+    
+    const response = await fetch(url, {
+      method,
+      headers: this.buildHeaders(hasBody),
+      body: hasBody ? JSON.stringify(payload) : undefined,
+    });
+
+    if (allow404 && response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      const detail = await response.text();
+      const error = new Error(`GitHub API ${method} ${url} failed: ${response.status} ${detail}`);
+      error.status = response.status;
+      throw error;
+    }
+
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+  }
+
+  async getPullRequest() {
+    return this.request(`/repos/${this.repo}/pulls/${this.prNumber}`);
+  }
+
+  async listPrFiles() {
+    const files = [];
+    for (let page = 1; ; page += 1) {
+      const params = new URLSearchParams({ per_page: "100", page: String(page) });
+      const batch = await this.request(`/repos/${this.repo}/pulls/${this.prNumber}/files?${params}`);
+      if (!batch || batch.length === 0) {
+        break;
+      }
+      files.push(...batch);
+      if (batch.length < 100) {
+        break;
+      }
+    }
+    return files;
+  }
+
+  async listIssueLabels() {
+    const labels = await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels`);
+    return new Set(labels.map((item) => item.name));
+  }
+
+  async syncLabelDefinition(name) {
+    const label = LABEL_DEFINITIONS[name];
+    const createUrl = `/repos/${this.repo}/labels`;
+    const updateUrl = `/repos/${this.repo}/labels/${encodeURIComponent(name)}`;
+
+    try {
+      await this.request(createUrl, {
+        method: "POST",
+        payload: { name, color: label.color, description: label.description },
+      });
+      log(`created label ${name}`);
+    } catch (error) {
+      if (error.status !== 422) {
+        throw error;
+      }
+      await this.request(updateUrl, {
+        method: "PATCH",
+        payload: { new_name: name, color: label.color, description: label.description },
+      });
+      log(`updated label ${name}`);
+    }
+  }
+
+  async addLabels(labels) {
+    if (labels.length === 0) return;
+    await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels`, {
+      method: "POST",
+      payload: { labels },
+    });
+    log(`added labels: ${labels.join(", ")}`);
+  }
+
+  async removeLabel(name) {
+    await this.request(`/repos/${this.repo}/issues/${this.prNumber}/labels/${encodeURIComponent(name)}`, {
+      method: "DELETE",
+      allow404: true,
+    });
+    log(`removed label: ${name}`);
+  }
+}
+
+// ============================================================================
+// Path & Domain Heuristics
+// ============================================================================
+
+function parsePrType(title) {
+  const match = String(title || "").trim().match(/^([a-z]+)(?:\([^)]+\))?!?:/i);
+  return match ? match[1].toLowerCase() : "";
+}
+
+function isLowRiskPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const basename = path.posix.basename(normalized);
+
+  if (normalized.startsWith("skills/lark-")) return false;
+  if (DOC_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) return true;
+  if (LOW_RISK_FILENAMES.has(basename)) return true;
+  if (LOW_RISK_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true;
+  if (LOW_RISK_TEST_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) return true;
+  return normalized.includes("/testdata/");
+}
+
+function isBusinessSkillPath(filePath) {
+  const normalized = normalizePath(filePath);
+  return normalized.startsWith("shortcuts/") || normalized.startsWith("skills/lark-");
+}
+
+function shortcutDomainForPath(filePath) {
+  const parts = normalizePath(filePath).split("/");
+  return parts.length >= 2 && parts[0] === "shortcuts" ? parts[1] : "";
+}
+
+function skillDomainForPath(filePath) {
+  const parts = normalizePath(filePath).split("/");
+  return parts.length >= 2 && parts[0] === "skills" && parts[1].startsWith("lark-")
+    ? parts[1].slice("lark-".length)
+    : "";
+}
+
+// Get business domain label based on CODEOWNERS path mapping
+function getBusinessDomain(filePath) {
+  const normalized = normalizePath(filePath);
+  for (const [prefix, domain] of Object.entries(PATH_TO_DOMAIN_MAP)) {
+    if (normalized.startsWith(prefix)) {
+      return domain;
+    }
+  }
+  return "";
+}
+
+async function detectNewShortcutDomain(files) {
+  for (const item of files) {
+    if (item.status !== "added") continue;
+    const domain = shortcutDomainForPath(item.filename);
+    if (!domain) continue;
+    try {
+      await fs.access(path.join(ROOT, "shortcuts", domain));
+    } catch {
+      return domain;
+    }
+  }
+  return "";
+}
+
+function collectCoreAreas(filenames) {
+  const areas = new Set();
+  for (const name of filenames) {
+    const normalized = normalizePath(name);
+    for (const prefix of CORE_PREFIXES) {
+      if (normalized.startsWith(prefix)) {
+        // remove trailing slash for area name
+        areas.add(prefix.slice(0, -1));
+      }
+    }
+  }
+  return areas;
+}
+
+function collectSensitiveKeywords(filenames) {
+  const hits = new Set();
+  for (const name of filenames) {
+    const match = normalizePath(name).match(SENSITIVE_PATTERN);
+    if (match && match[2]) {
+      hits.add(match[2]);
+    }
+  }
+  return [...hits].sort();
+}
+
+// ============================================================================
+// Classification Logic
+// ============================================================================
+
+function evaluateRules(context) {
+  const {
+    prType, effectiveChanges, lowRiskOnly,
+    domains, headDomains, coreAreas, coreSignals,
+    sensitiveKeywords, sensitive, newShortcutDomain,
+    singleDomain, multiDomain, filenames
+  } = context;
+
+  const reasons = [];
+  let label;
+
+  if (lowRiskOnly && (LOW_RISK_TYPES.has(prType) || effectiveChanges === 0)) {
+    reasons.push("Only low-risk docs, CI, test, or chore paths were changed, with no effective business code or Skill changes");
+    label = "size/S";
+    return { label, reasons };
+  }
+
+  // XL is reserved for architecture-level or global-impact changes.
+  const isXL =
+    effectiveChanges > THRESHOLD_XL ||
+    (prType === "refactor" && sensitive && effectiveChanges >= THRESHOLD_L) ||
+    (coreAreas.size >= 2 && (multiDomain || effectiveChanges >= THRESHOLD_L)) ||
+    (headDomains.length >= 2 && sensitive);
+
+  if (isXL) {
+    if (effectiveChanges > THRESHOLD_XL) reasons.push("Effective business code or Skill changes are far beyond the L threshold");
+    if (prType === "refactor" && sensitive && effectiveChanges >= THRESHOLD_L) reasons.push("Refactor PR touches core or sensitive paths");
+    if (coreAreas.size >= 2) reasons.push("Touches multiple core areas at the same time");
+    if (headDomains.length >= 2) reasons.push("Impacts multiple major business domains");
+    coreSignals.forEach((signal) => reasons.push(`Core area hit: ${signal}`));
+    sensitiveKeywords.forEach((keyword) => reasons.push(`Sensitive keyword hit: ${keyword}`));
+    label = "size/XL";
+  } else if (
+    prType === "refactor" ||
+    effectiveChanges >= THRESHOLD_L ||
+    Boolean(newShortcutDomain) ||
+    multiDomain ||
+    sensitive
+  ) {
+    if (prType === "refactor") reasons.push("PR type is refactor");
+    if (effectiveChanges >= THRESHOLD_L) reasons.push(`Effective business code or Skill changes exceed ${THRESHOLD_L} lines`);
+    if (newShortcutDomain) reasons.push(`Introduces a new business domain directory: shortcuts/${newShortcutDomain}/`);
+    if (multiDomain) reasons.push("Touches multiple business domains");
+    coreSignals.forEach((signal) => reasons.push(`Core area hit: ${signal}`));
+    sensitiveKeywords.forEach((keyword) => reasons.push(`Sensitive keyword hit: ${keyword}`));
+    label = "size/L";
+  } else {
+    if (filenames.some(isBusinessSkillPath) || effectiveChanges > 0) {
+      reasons.push("Regular feat, fix, or Skill change within a single business domain");
+    }
+    if (singleDomain && domains.size > 0) {
+      reasons.push(`Impact is limited to a single business domain: ${[...domains].sort().join(", ")}`);
+    }
+    if (effectiveChanges < THRESHOLD_L) {
+      reasons.push(`Effective business code or Skill changes are below ${THRESHOLD_L} lines`);
+    }
+    label = "size/M";
+  }
+
+  return { label, reasons };
+}
+
+async function classifyPr(payload, files) {
+  const pr = payload.pull_request;
+  const title = pr.title || "";
+  const prType = parsePrType(title);
+  const filenames = files.map((item) => item.filename || "");
+  const impactedPaths = files.flatMap((item) => {
+    const paths = [item.filename || ""];
+    if (item.status === "renamed" && item.previous_filename) {
+      paths.push(item.previous_filename);
+    }
+    return paths.filter(Boolean);
+  });
+  
+  // Filter out docs, tests, and other low-risk paths so the size label tracks business impact.
+  const effectiveChanges = files.reduce(
+    (sum, item) => sum + (isLowRiskPath(item.filename) ? 0 : (item.changes || 0)),
+    0,
+  );
+  const totalChanges = files.reduce((sum, item) => sum + (item.changes || 0), 0);
+  
+  const domains = new Set();
+  const businessDomains = new Set();
+
+  for (const name of impactedPaths) {
+    const businessDomain = getBusinessDomain(name);
+    if (businessDomain) {
+      businessDomains.add(businessDomain);
+      domains.add(businessDomain);
+      continue;
+    }
+
+    const shortcutDomain = shortcutDomainForPath(name);
+    if (shortcutDomain) domains.add(shortcutDomain);
+
+    const skillDomain = skillDomainForPath(name);
+    if (skillDomain) domains.add(skillDomain);
+  }
+
+  const coreAreas = collectCoreAreas(impactedPaths);
+  const newShortcutDomain = await detectNewShortcutDomain(files);
+  
+  const lowRiskOnly = impactedPaths.length > 0 && impactedPaths.every(isLowRiskPath);
+  const singleDomain = domains.size <= 1;
+  const multiDomain = domains.size >= 2;
+  const headDomains = [...domains].filter((domain) => HEAD_BUSINESS_DOMAINS.has(domain));
+  const coreSignals = [...coreAreas].sort();
+  const sensitiveKeywords = collectSensitiveKeywords(impactedPaths);
+  const sensitive = coreSignals.length > 0 || sensitiveKeywords.length > 0;
+
+  const context = {
+    prType, effectiveChanges, lowRiskOnly,
+    domains, headDomains, coreAreas, coreSignals,
+    sensitiveKeywords, sensitive, newShortcutDomain,
+    singleDomain, multiDomain, filenames: impactedPaths
+  };
+
+  const { label, reasons } = evaluateRules(context);
+
+  return {
+    label,
+    title,
+    prType: prType || "unknown",
+    totalChanges,
+    effectiveChanges,
+    domains: [...domains].sort(),
+    businessDomains: [...businessDomains].sort(),
+    coreAreas: [...coreAreas].sort(),
+    coreSignals,
+    sensitiveKeywords,
+    newShortcutDomain,
+    reasons,
+    lowRiskOnly,
+    filenames,
+  };
+}
+
+// ============================================================================
+// Output & Formatting
+// ============================================================================
+
+async function writeStepSummary(prNumber, classification) {
+  const summaryPath = (process.env.GITHUB_STEP_SUMMARY || "").trim();
+  if (!summaryPath) return;
+
+  const standard = CLASS_STANDARDS[classification.label];
+  const domains = classification.domains.join(", ") || "-";
+  const bDomains = classification.businessDomains.join(", ") || "-";
+  const coreAreas = classification.coreAreas.join(", ") || "-";
+  const reasons = classification.reasons.length > 0
+    ? classification.reasons
+    : ["No higher-severity rule matched, so the PR defaults to medium classification"];
+
+  const lines = [
+    "## PR Size Classification",
+    "",
+    `- PR: #${prNumber}`,
+    `- Label: \`${classification.label}\``,
+    `- PR Type: \`${classification.prType}\``,
+    `- Total Changes: \`${classification.totalChanges}\``,
+    `- Effective Business/SKILL Changes: \`${classification.effectiveChanges}\``,
+    `- Business Domains: \`${domains}\``,
+    `- Impacted Domains: \`${bDomains}\``,
+    `- Core Areas: \`${coreAreas}\``,
+    `- CI/CD Channel: \`${standard.channel}\``,
+    `- Low Risk Only: \`${classification.lowRiskOnly}\``,
+    "",
+    "### Reasons",
+    "",
+    ...reasons.map((reason) => `- ${reason}`),
+    "",
+    "### Pipeline Gates",
+    "",
+    ...standard.gates.map((gate) => `- ${gate}`),
+    "",
+  ];
+
+  await fs.appendFile(summaryPath, `${lines.join("\n")}\n`, "utf8");
+}
+
+function formatDryRunResult(repo, prNumber, classification) {
+  const standard = CLASS_STANDARDS[classification.label];
+  return {
+    repo,
+    prNumber,
+    label: classification.label,
+    prType: classification.prType,
+    totalChanges: classification.totalChanges,
+    effectiveChanges: classification.effectiveChanges,
+    lowRiskOnly: classification.lowRiskOnly,
+    domains: classification.domains,
+    businessDomains: classification.businessDomains,
+    coreAreas: classification.coreAreas,
+    coreSignals: classification.coreSignals,
+    sensitiveKeywords: classification.sensitiveKeywords,
+    reasons: classification.reasons,
+    channel: standard.channel,
+    gates: standard.gates,
+  };
+}
+
+function printDryRunResult(result, options) {
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const signalParts = [
+    ...result.coreSignals.map((signal) => `core:${signal}`),
+    ...result.sensitiveKeywords.map((keyword) => `keyword:${keyword}`),
+    ...(result.domains.length > 0 ? [`domains:${result.domains.join(",")}`] : []),
+  ];
+  const reasonParts = result.reasons.length > 0
+    ? result.reasons
+    : ["No higher-severity rule matched, so the PR defaults to medium classification"];
+  
+  console.log(
+    `${result.label} | #${result.prNumber} | type:${result.prType} | eff:${result.effectiveChanges} | `
+      + `sig:${signalParts.join(";") || "-"} | reason:${reasonParts.join("; ")}`,
+  );
+}
+
+function printHelp() {
+  const lines = [
+    "Usage:",
+    "  node scripts/pr-labels/index.js",
+    "  node scripts/pr-labels/index.js --dry-run --pr-url <github-pr-url> [--token <token>] [--json]",
+    "  node scripts/pr-labels/index.js --dry-run --repo <owner/name> --pr-number <number> [--token <token>] [--json]",
+    "",
+    "Modes:",
+    "  default    Read the GitHub Actions event payload and apply labels",
+    "  --dry-run  Fetch the PR, compute the managed label, and print the result without writing labels",
+    "",
+    "Options:",
+    "  --pr-url <url>       GitHub pull request URL, for example https://github.com/larksuite/cli/pull/123",
+    "  --repo <owner/name>  Repository name, used with --pr-number",
+    "  --pr-number <n>      Pull request number, used with --repo",
+    "  --token <token>      GitHub token override; falls back to GITHUB_TOKEN",
+    "  --json               Print dry-run output as JSON instead of the default one-line summary",
+    "  --help               Show this message",
+  ];
+  console.log(lines.join("\n"));
+}
+
+function parseArgs(argv) {
+  const options = {
+    dryRun: false,
+    json: false,
+    help: false,
+    prUrl: "",
+    repo: "",
+    prNumber: "",
+    token: "",
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--json") options.json = true;
+    else if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--pr-url") options.prUrl = argv[++i] || "";
+    else if (arg === "--repo") options.repo = argv[++i] || "";
+    else if (arg === "--pr-number") options.prNumber = argv[++i] || "";
+    else if (arg === "--token") options.token = argv[++i] || "";
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function parsePrUrl(prUrl) {
+  let parsed;
+  try {
+    parsed = new URL(prUrl);
+  } catch {
+    throw new Error(`invalid PR URL: ${prUrl}`);
+  }
+
+  const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
+  if (!match) throw new Error(`unsupported PR URL format: ${prUrl}`);
+
+  return { repo: `${match[1]}/${match[2]}`, prNumber: Number(match[3]) };
+}
+
+async function loadEventPayload(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+async function resolveContext(options) {
+  const token = options.token;
+
+  if (options.prUrl) {
+    const { repo, prNumber } = parsePrUrl(options.prUrl);
+    const client = new GitHubClient(token, repo, prNumber);
+    const payload = {
+      repository: { full_name: repo },
+      pull_request: await client.getPullRequest(),
+    };
+    return { repo, prNumber, payload, client };
+  }
+
+  if (options.repo || options.prNumber) {
+    if (!options.repo || !options.prNumber) throw new Error("--repo and --pr-number must be provided together");
+    const prNumber = Number(options.prNumber);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error(`invalid PR number: ${options.prNumber}`);
+    
+    const client = new GitHubClient(token, options.repo, prNumber);
+    const payload = {
+      repository: { full_name: options.repo },
+      pull_request: await client.getPullRequest(),
+    };
+    return { repo: options.repo, prNumber, payload, client };
+  }
+
+  const eventPath = envOrFail("GITHUB_EVENT_PATH");
+  const payload = await loadEventPayload(eventPath);
+  const repo = payload.repository.full_name;
+  const prNumber = payload.pull_request.number;
+  const client = new GitHubClient(token, repo, prNumber);
+
+  return { repo, prNumber, payload, client };
+}
+
+// ============================================================================
+// Main Execution
+// ============================================================================
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  options.token = options.token || envValue("GITHUB_TOKEN");
+
+  if (!options.dryRun && !options.token) {
+    throw new Error("missing required GitHub token; set GITHUB_TOKEN or pass --token");
+  }
+
+  const { repo, prNumber, payload, client } = await resolveContext(options);
+
+  const files = await client.listPrFiles();
+  const classification = await classifyPr(payload, files);
+
+  if (options.dryRun) {
+    printDryRunResult(formatDryRunResult(repo, prNumber, classification), options);
+    return;
+  }
+
+  const desired = new Set([classification.label]);
+  for (const domain of classification.businessDomains) {
+    desired.add(`domain/${domain}`);
+  }
+
+  const current = await client.listIssueLabels();
+  const managedCurrent = [...current].filter((label) => MANAGED_LABELS.has(label) || label.startsWith("domain/"));
+  const toAdd = [...desired].filter((label) => !current.has(label)).sort();
+  const toRemove = managedCurrent.filter((label) => !desired.has(label)).sort();
+
+  for (const domain of classification.businessDomains) {
+    const labelName = `domain/${domain}`;
+    if (!LABEL_DEFINITIONS[labelName]) {
+      LABEL_DEFINITIONS[labelName] = { color: "1d76db", description: `PR touches the ${domain} domain` };
+    }
+  }
+
+  // Ensure labels to be added actually exist in the repository first
+  // If the label doesn't exist, GitHub API will return 422 Unprocessable Entity when trying to add it to a PR.
+  for (const label of toAdd) {
+    if (LABEL_DEFINITIONS[label]) {
+      try {
+        await client.syncLabelDefinition(label);
+      } catch (e) {
+        log(`Warning: Failed to bootstrap new label ${label}: ${e.message}`);
+      }
+    }
+  }
+
+  await client.addLabels(toAdd);
+
+  for (const label of toRemove) {
+    await client.removeLabel(label);
+  }
+
+  // Keep other label metadata consistent. This is best-effort trailing work.
+  for (const label of Object.keys(LABEL_DEFINITIONS)) {
+    if (toAdd.includes(label)) continue; // Already synced above
+    try {
+      await client.syncLabelDefinition(label);
+    } catch (e) {
+      log(`Warning: Failed to sync label definition for ${label}: ${e.message}`);
+    }
+  }
+
+  await writeStepSummary(prNumber, classification);
+
+  log(
+    `pr #${prNumber} type=${classification.prType} total_changes=${classification.totalChanges} `
+      + `effective_changes=${classification.effectiveChanges} files=${files.length} `
+      + `desired=${[...desired].sort().join(",") || "-"} current_managed=${managedCurrent.sort().join(",") || "-"} `
+      + `reasons=${classification.reasons.join(" | ") || "-"}`,
+  );
+}
+
+main().catch((error) => {
+  log(error.message || String(error));
+  process.exit(1);
+});

scripts/pr-labels/samples.json

@@ -0,0 +1,145 @@
+[
+  {
+    "name": "size-s-docs-badge",
+    "number": 103,
+    "title": "docs: add official badge to distinguish from third-party Lark CLI tools",
+    "pr_url": "https://github.com/larksuite/cli/pull/103",
+    "status": "merged",
+    "merged_at": "2026-03-30T12:15:45Z",
+    "expected_label": "size/S",
+    "expected_domains": [],
+    "review_note": "Pure docs sample. Useful to confirm low-risk paths stay in S even when total changed lines are not tiny."
+  },
+  {
+    "name": "size-s-docs-simplify",
+    "number": 26,
+    "title": "docs: simplify installation steps by merging CLI and Skills into one …",
+    "pr_url": "https://github.com/larksuite/cli/pull/26",
+    "status": "merged",
+    "merged_at": "2026-03-28T09:33:24Z",
+    "expected_label": "size/S",
+    "expected_domains": [],
+    "review_note": "Docs sample, verifying docs changes remain in S."
+  },
+  {
+    "name": "size-s-docs-star-history",
+    "number": 12,
+    "title": "docs: add Star History chart to readmes",
+    "pr_url": "https://github.com/larksuite/cli/pull/12",
+    "status": "merged",
+    "merged_at": "2026-03-28T16:00:15Z",
+    "expected_label": "size/S",
+    "expected_domains": [],
+    "review_note": "Docs sample, no effective business code changes."
+  },
+  {
+    "name": "size-s-docs-clarify-install",
+    "number": 3,
+    "title": "docs: clarify install methods and add source build steps",
+    "pr_url": "https://github.com/larksuite/cli/pull/3",
+    "status": "merged",
+    "merged_at": "2026-03-28T03:43:44Z",
+    "expected_label": "size/S",
+    "expected_domains": [],
+    "review_note": "Docs sample, pure documentation clarification."
+  },
+  {
+    "name": "size-m-fix-base-scope",
+    "number": 96,
+    "title": "fix(base): correct scope for record history list shortcut",
+    "pr_url": "https://github.com/larksuite/cli/pull/96",
+    "status": "merged",
+    "merged_at": "2026-03-30T11:40:18Z",
+    "expected_label": "size/M",
+    "expected_domains": ["domain/base"],
+    "review_note": "Small fix sample. Verify the lower edge of the M bucket within a single domain."
+  },
+  {
+    "name": "size-m-fix-mail-sensitive",
+    "number": 92,
+    "title": "fix: remove sensitive send scope from reply and forward shortcuts",
+    "pr_url": "https://github.com/larksuite/cli/pull/92",
+    "status": "merged",
+    "merged_at": "2026-03-30T10:19:11Z",
+    "expected_label": "size/M",
+    "expected_domains": ["domain/mail"],
+    "review_note": "Security-like wording in the title but stays in one business domain (mail)."
+  },
+  {
+    "name": "size-m-ci-improve",
+    "number": 71,
+    "title": "ci: improve CI workflows and add golangci-lint config",
+    "pr_url": "https://github.com/larksuite/cli/pull/71",
+    "status": "merged",
+    "merged_at": "2026-03-30T03:09:31Z",
+    "expected_label": "size/M",
+    "expected_domains": [],
+    "review_note": "CI workflow change that goes beyond S threshold."
+  },
+  {
+    "name": "size-m-feat-im-pagination",
+    "number": 30,
+    "title": "feat: add auto-pagination to messages search and update lark-im docs",
+    "pr_url": "https://github.com/larksuite/cli/pull/30",
+    "status": "merged",
+    "merged_at": "2026-03-30T15:00:41Z",
+    "expected_label": "size/M",
+    "expected_domains": ["domain/im"],
+    "review_note": "Single-domain feature with larger diff but effective changes stay in M."
+  },
+  {
+    "name": "size-l-fix-api-silent",
+    "number": 85,
+    "title": "fix: resolve silent failure in `lark-cli api` error output (#39)",
+    "pr_url": "https://github.com/larksuite/cli/pull/85",
+    "status": "merged",
+    "merged_at": "2026-03-30T09:19:24Z",
+    "expected_label": "size/L",
+    "expected_domains": [],
+    "review_note": "Touches core area (cmd), bumping the size to L."
+  },
+  {
+    "name": "size-l-fix-cli",
+    "number": 91,
+    "title": "fix: correct CLI examples in root help and READMEs (closes #48)",
+    "pr_url": "https://github.com/larksuite/cli/pull/91",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/L",
+    "expected_domains": [],
+    "review_note": "Closed PR touching core area (cmd)."
+  },
+  {
+    "name": "size-m-skill-format-check",
+    "number": 134,
+    "title": "feat(ci): add skill format check workflow to ensure SKILL.md compliance",
+    "pr_url": "https://github.com/larksuite/cli/pull/134",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/M",
+    "expected_domains": [],
+    "review_note": "Includes updates to tests/bad-skill/SKILL.md inside skills-like paths, testing how skill mock files and test scripts are handled."
+  },
+  {
+    "name": "size-l-ccm-multi-path",
+    "number": 57,
+    "title": "feat(docs): support local image upload in docs +create",
+    "pr_url": "https://github.com/larksuite/cli/pull/57",
+    "status": "closed",
+    "merged_at": null,
+    "expected_label": "size/L",
+    "expected_domains": ["domain/ccm"],
+    "review_note": "Touches docs_create_images.go and table_auto_width.go, representing multiple CCM sub-paths but resolving to a single ccm domain."
+  },
+  {
+    "name": "size-l-domain-rename",
+    "number": 11,
+    "title": "docs: rename user-facing Bitable references to Base",
+    "pr_url": "https://github.com/larksuite/cli/pull/11",
+    "status": "merged",
+    "merged_at": "2026-03-28T16:00:52Z",
+    "expected_label": "size/L",
+    "expected_domains": ["domain/base", "domain/ccm"],
+    "review_note": "A rename across paths. Since we track previous_filename to evaluate domains, this should properly capture the base domain."
+  }
+]

scripts/pr-labels/test.js

@@ -0,0 +1,52 @@
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const samplesPath = path.join(__dirname, 'samples.json');
+const indexPath = path.join(__dirname, 'index.js');
+const samples = JSON.parse(fs.readFileSync(samplesPath, 'utf8'));
+
+if (!process.env.GITHUB_TOKEN) {
+  console.error("❌ Error: GITHUB_TOKEN environment variable is required to run tests without hitting API rate limits.");
+  console.error("Please run: GITHUB_TOKEN=$(gh auth token) node scripts/pr-labels/test.js");
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+for (const sample of samples) {
+  try {
+    const output = execFileSync(
+      process.execPath,
+      [indexPath, '--dry-run', '--json', '--pr-url', sample.pr_url],
+      { encoding: 'utf8', env: process.env }
+    );
+    const result = JSON.parse(output);
+
+    const matchLabel = result.label === sample.expected_label;
+    
+    // Sort before comparing to ignore order
+    const actualDomains = (result.businessDomains || []).sort();
+    const expectedDomains = (sample.expected_domains || []).map(d => d.replace('domain/', '')).sort();
+    
+    const matchDomains = JSON.stringify(actualDomains) === JSON.stringify(expectedDomains);
+
+    if (matchLabel && matchDomains) {
+      console.log(`✅ Passed: ${sample.name}`);
+      passed++;
+    } else {
+      console.log(`❌ Failed: ${sample.name}`);
+      console.log(`   Label expected: ${sample.expected_label}, got: ${result.label}`);
+      console.log(`   Domains expected: ${expectedDomains}, got: ${actualDomains}`);
+      failed++;
+    }
+  } catch (e) {
+    console.log(`❌ Failed: ${sample.name} (Execution error)`);
+    console.error(e.message);
+    failed++;
+  }
+}
+
+console.log(`\nTest Summary: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

scripts/skill-format-check/README.md

@@ -0,0 +1,36 @@
+# Skill Format Check
+
+This directory contains a script to validate the format of `SKILL.md` files located in the `../../skills` directory.
+
+## Purpose
+
+The `index.js` script ensures that all `SKILL.md` files conform to the standard template defined in `skill-template/skill-template.md`. Specifically, it checks that the YAML frontmatter includes the following fields:
+- `name` (required)
+- `description` (required)
+- `metadata` (outputs a warning if missing, does not fail the build)
+
+> **Note:** The `lark-shared` skill is explicitly excluded from these format checks.
+
+## Usage
+
+This script is executed automatically via GitHub Actions (`.github/workflows/skill-format-check.yml`) on pull requests and pushes that modify the `skills/` directory.
+
+To run the check manually from the root of the repository, execute:
+
+```bash
+node scripts/skill-format-check/index.js
+```
+
+You can also specify a custom target directory as the first argument:
+
+```bash
+node scripts/skill-format-check/index.js ./path/to/my/skills
+```
+
+## Testing
+
+This tool comes with a quick validation script to ensure it correctly identifies good and bad skill formats. To run the tests, execute:
+
+```bash
+./scripts/skill-format-check/test.sh
+```

scripts/skill-format-check/index.js

@@ -0,0 +1,96 @@
+const fs = require('fs');
+const path = require('path');
+
+// Allow passing a target directory as the first argument.
+// If provided, resolve against process.cwd() so it behaves as the user expects.
+// If not provided, default to '../../skills' relative to this script's directory.
+const targetDirArg = process.argv[2];
+const SKILLS_DIR = targetDirArg
+  ? path.resolve(process.cwd(), targetDirArg)
+  : path.resolve(__dirname, '../../skills');
+
+function checkSkillFormat() {
+  console.log(`Checking skill format in ${SKILLS_DIR}...`);
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  let skills;
+  try {
+    skills = fs
+      .readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name);
+  } catch (err) {
+    console.error(`Failed to enumerate skills directory: ${err.message}`);
+    process.exit(1);
+  }
+
+  let hasErrors = false;
+
+  skills.forEach(skill => {
+    // Skip lark-shared skill completely
+    if (skill === 'lark-shared') {
+        console.log(`⏭️  Skipping check for ${skill}`);
+        return;
+    }
+
+    const skillPath = path.join(SKILLS_DIR, skill);
+    const skillFile = path.join(skillPath, 'SKILL.md');
+
+    if (!fs.existsSync(skillFile)) {
+      console.error(`❌ [${skill}] Missing SKILL.md`);
+      hasErrors = true;
+      return;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(skillFile, 'utf-8');
+    } catch (err) {
+      console.error(`❌ [${skill}] Failed to read SKILL.md: ${err.message}`);
+      hasErrors = true;
+      return;
+    }
+
+    // Normalize line endings to simplify parsing
+    const normalizedContent = content.replace(/\r\n/g, '\n');
+
+    // Check YAML Frontmatter
+    if (!normalizedContent.startsWith('---\n')) {
+       console.error(`❌ [${skill}] SKILL.md must start with YAML frontmatter (---)`);
+       hasErrors = true;
+    } else {
+        const frontmatterMatch = normalizedContent.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+        if (!frontmatterMatch) {
+             console.error(`❌ [${skill}] SKILL.md has unclosed or invalid YAML frontmatter`);
+             hasErrors = true;
+        } else {
+            const frontmatter = frontmatterMatch[1];
+            if (!/^name:/m.test(frontmatter)) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'name'`);
+                hasErrors = true;
+            }
+            if (!/^description:/m.test(frontmatter)) {
+                console.error(`❌ [${skill}] YAML frontmatter missing 'description'`);
+                hasErrors = true;
+            }
+            if (!/^metadata:/m.test(frontmatter)) {
+                console.warn(`⚠️  [${skill}] YAML frontmatter missing 'metadata' (Warning only)`);
+                // hasErrors = true; // Downgrade to warning to not fail on existing skills
+            }
+        }
+    }
+  });
+
+  if (hasErrors) {
+    console.error('\n❌ Skill format check failed. Please fix the errors above.');
+    process.exit(1);
+  } else {
+    console.log('\n✅ Skill format check passed!');
+  }
+}
+
+checkSkillFormat();

scripts/skill-format-check/test.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# Get the directory of this script
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+INDEX_JS="$DIR/index.js"
+TEMP_DIR="$DIR/tests/temp_test_dir"
+
+echo "=== Running tests for skill-format-check ==="
+echo "Index script: $INDEX_JS"
+
+prepare_fixture() {
+    local test_name=$1
+    rm -rf "$TEMP_DIR"
+    mkdir -p "$TEMP_DIR"
+    if [ ! -d "$DIR/tests/$test_name" ]; then
+        echo "❌ Missing fixture directory: $DIR/tests/$test_name"
+        exit 1
+    fi
+    cp -r "$DIR/tests/$test_name" "$TEMP_DIR/" || {
+        echo "❌ Failed to copy fixture: $test_name"
+        exit 1
+    }
+}
+
+# Function to run a positive test
+run_positive_test() {
+    local test_name=$1
+    echo -e "\n--- [Positive] $test_name ---"
+    
+    prepare_fixture "$test_name"
+    
+    node "$INDEX_JS" "$TEMP_DIR"
+    
+    if [ $? -eq 0 ]; then
+        echo "✅ Passed! (Correctly validated $test_name)"
+        rm -rf "$TEMP_DIR"
+        return 0
+    else
+        echo "❌ Failed! Expected $test_name to pass but it failed."
+        rm -rf "$TEMP_DIR"
+        exit 1
+    fi
+}
+
+# Function to run a negative test
+run_negative_test() {
+    local test_name=$1
+    echo -e "\n--- [Negative] $test_name ---"
+    
+    prepare_fixture "$test_name"
+    
+    # Capture output for diagnostics while still treating non-zero as expected
+    local log_file="$TEMP_DIR/.validator.log"
+    node "$INDEX_JS" "$TEMP_DIR" > "$log_file" 2>&1
+    local exit_code=$?
+    
+    if [ $exit_code -ne 0 ]; then
+        echo "✅ Passed! (Correctly rejected $test_name)"
+        rm -rf "$TEMP_DIR"
+        return 0
+    else
+        echo "❌ Failed! Expected $test_name to fail but it passed."
+        if [ -s "$log_file" ]; then
+            echo "--- Validator output ---"
+            cat "$log_file"
+        fi
+        rm -rf "$TEMP_DIR"
+        exit 1
+    fi
+}
+
+# Run positive tests
+run_positive_test "good-skill"
+run_positive_test "good-skill-minimal"
+run_positive_test "good-skill-complex"
+
+# Run negative tests
+run_negative_test "bad-skill"
+run_negative_test "bad-skill-no-frontmatter"
+run_negative_test "bad-skill-unclosed-frontmatter"
+
+echo -e "\n🎉 All tests passed successfully!"

scripts/skill-format-check/tests/bad-skill-no-frontmatter/SKILL.md

@@ -0,0 +1,3 @@
+# No Frontmatter Skill
+
+This skill completely lacks a YAML frontmatter.

scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: bad-skill-unclosed
+version: 1.0.0
+description: "This skill has an unclosed frontmatter block."
+metadata: {}
+
+# Unclosed Frontmatter Skill
+
+This frontmatter does not have a closing `---` block.

scripts/skill-format-check/tests/bad-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+version: 1.0.0
+metadata: {}
+---
+
+# Bad Skill
+
+This skill is missing required fields like name and description.

scripts/skill-format-check/tests/good-skill-complex/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: good-skill-complex
+version: 2.5.1-beta
+description: >
+  A very complex description
+  that spans multiple lines
+  and contains weird chars: !@#$%^&*()
+metadata:
+  requires:
+    bins: ["lark-cli", "node"]
+  cliHelp: "lark-cli something --help"
+  customField: "customValue"
+---
+
+# Complex Skill
+
+This skill has a complex frontmatter block.

scripts/skill-format-check/tests/good-skill-minimal/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: good-skill-minimal
+version: 0.1.0
+description: Minimal valid description
+metadata: {}
+---
+
+# Minimal Skill
+
+This has the bare minimum required fields.

scripts/skill-format-check/tests/good-skill/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: good-skill
+version: 1.0.0
+description: "This is a properly formatted skill."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+
+# Good Skill
+
+This skill follows all the formatting rules.

shortcuts/base/base_data_query.go

@@ -14,7 +14,7 @@ import (
 var BaseDataQuery = common.Shortcut{
 	Service:     "base",
 	Command:     "+data-query",
-	Description: "Query and analyze Bitable data with JSON DSL (aggregation, filter, sort)",
+	Description: "Query and analyze Base data with JSON DSL (aggregation, filter, sort)",
 	Risk:        "read",
 	Scopes:      []string{"base:table:read"},
 	AuthTypes:   authTypes(),

shortcuts/base/dashboard_block_create.go

@@ -23,7 +23,7 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
 		{Name: "name", Desc: "block name", Required: true},
-		{Name: "type", Desc: "block type: column / bar / line / pie / ring / area / combo / scatter / funnel / wordCloud / radar / statistics", Required: true},
+		{Name: "type", Desc: "block type: column(柱状图)|bar(条形图)|line(折线图)|pie(饼图)|ring(环形图)|area(面积图)|combo(组合图)|scatter(散点图)|funnel(漏斗图)|wordCloud(词云)|radar(雷达图)|statistics(指标卡). Read dashboard-block-data-config.md before creating.", Required: true},
 		{Name: "data-config", Desc: "data config JSON object (table_name, series, count_all, group_by, filter, etc.)"},
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},

shortcuts/base/dashboard_block_update.go

@@ -24,7 +24,7 @@ var BaseDashboardBlockUpdate = common.Shortcut{
 		dashboardIDFlag(true),
 		blockIDFlag(true),
 		{Name: "name", Desc: "new block name"},
-		{Name: "data-config", Desc: "data config JSON object (table_name, series, count_all, group_by, filter, etc.)"},
+		{Name: "data-config", Desc: "data config JSON: table_name, series|count_all (mutually exclusive), group_by, filter. See dashboard-block-data-config.md for details."},
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},

shortcuts/base/record_history_list.go

@@ -14,7 +14,7 @@ var BaseRecordHistoryList = common.Shortcut{
 	Command:     "+record-history-list",
 	Description: "List record change history",
 	Risk:        "read",
-	Scopes:      []string{"base:record:read"},
+	Scopes:      []string{"base:history:read"},
 	AuthTypes:   authTypes(),
 	Flags: []common.Flag{
 		baseTokenFlag(true),

shortcuts/calendar/calendar_agenda.go

@@ -178,6 +178,9 @@ var CalendarAgenda = common.Shortcut{
 		{Name: "end", Desc: "end time (ISO 8601, default: end of start day)"},
 		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return rejectCalendarAutoBotFallback(runtime)
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		startInt, endInt, err := parseTimeRange(runtime)
 		if err != nil {

shortcuts/calendar/calendar_create.go

@@ -81,6 +81,9 @@ var CalendarCreate = common.Shortcut{
 		{Name: "rrule", Desc: "recurrence rule (rfc5545)"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
 		for _, flag := range []string{"summary", "description", "rrule", "calendar-id"} {
 			if val := runtime.Str(flag); val != "" {
 				if err := common.RejectDangerousChars("--"+flag, val); err != nil {

shortcuts/calendar/calendar_freebusy.go

@@ -68,6 +68,9 @@ var CalendarFreebusy = common.Shortcut{
 			Body(map[string]interface{}{"time_min": timeMin, "time_max": timeMax, "user_id": userId, "need_rsvp_status": true})
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
 		userId := runtime.Str("user-id")
 		if userId == "" && runtime.IsBot() {
 			return common.FlagErrorf("--user-id is required for bot identity")

shortcuts/calendar/calendar_rsvp.go

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var CalendarRsvp = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+rsvp",
+	Description: "Reply to a calendar event (accept/decline/tentative)",
+	Risk:        "write",
+	Scopes:      []string{"calendar:calendar.event:reply"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   false,
+	Flags: []common.Flag{
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+		{Name: "event-id", Desc: "event ID", Required: true},
+		{Name: "rsvp-status", Desc: "reply status", Required: true, Enum: []string{"accept", "decline", "tentative"}},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		d := common.NewDryRunAPI()
+		switch calendarId {
+		case "":
+			d.Desc("(calendar-id omitted) Will use primary calendar")
+			calendarId = "<primary>"
+		case "primary":
+			calendarId = "<primary>"
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		status := strings.TrimSpace(runtime.Str("rsvp-status"))
+
+		return d.
+			POST("/open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/reply").
+			Body(map[string]interface{}{"rsvp_status": status}).
+			Set("calendar_id", calendarId).
+			Set("event_id", eventId)
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		for _, flag := range []string{"calendar-id", "event-id", "rsvp-status"} {
+			if val := strings.TrimSpace(runtime.Str(flag)); val != "" {
+				if err := common.RejectDangerousChars("--"+flag, val); err != nil {
+					return output.ErrValidation(err.Error())
+				}
+			}
+		}
+
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		if eventId == "" {
+			return output.ErrValidation("event-id cannot be empty")
+		}
+		return nil
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarId == "" {
+			calendarId = PrimaryCalendarIDStr
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		status := strings.TrimSpace(runtime.Str("rsvp-status"))
+
+		_, err := runtime.DoAPIJSON("POST",
+			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s/reply",
+				validate.EncodePathSegment(calendarId),
+				validate.EncodePathSegment(eventId)),
+			nil,
+			map[string]interface{}{
+				"rsvp_status": status,
+			})
+		if err != nil {
+			return err
+		}
+
+		runtime.Out(map[string]interface{}{
+			"calendar_id": calendarId,
+			"event_id":    eventId,
+			"rsvp_status": status,
+		}, nil)
+		return nil
+	},
+}

shortcuts/calendar/calendar_suggestion.go

@@ -214,6 +214,9 @@ var CalendarSuggestion = common.Shortcut{
 			Body(req)
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
 		durationMinutes := runtime.Int(flagDurationMinutes)
 		if durationMinutes != 0 && (durationMinutes < 1 || durationMinutes > 1440) {
 			return output.ErrValidation("--duration-minutes must be between 1 and 1440")

shortcuts/calendar/calendar_test.go

@@ -82,6 +82,19 @@ func defaultConfig() *core.CliConfig {
 	}
 }
 
+func noLoginConfig() *core.CliConfig {
+	return &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+}
+
+func noLoginBotDefaultConfig() *core.CliConfig {
+	return &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+		DefaultAs: "bot",
+	}
+}
+
 // ---------------------------------------------------------------------------
 // CalendarCreate tests
 // ---------------------------------------------------------------------------
@@ -337,6 +350,108 @@ func TestCreate_NoEventIdReturned(t *testing.T) {
 // CalendarAgenda tests
 // ---------------------------------------------------------------------------
 
+func TestCalendarShortcuts_RequireLoginUnlessExplicitBot(t *testing.T) {
+	cases := []struct {
+		name     string
+		shortcut common.Shortcut
+		args     []string
+	}{
+		{
+			name:     "agenda",
+			shortcut: CalendarAgenda,
+			args:     []string{"+agenda", "--start", "2025-03-21", "--end", "2025-03-21"},
+		},
+		{
+			name:     "create",
+			shortcut: CalendarCreate,
+			args:     []string{"+create", "--summary", "Test Meeting", "--start", "2025-03-21T00:00:00+08:00", "--end", "2025-03-21T01:00:00+08:00"},
+		},
+		{
+			name:     "freebusy",
+			shortcut: CalendarFreebusy,
+			args:     []string{"+freebusy", "--start", "2025-03-21", "--end", "2025-03-21"},
+		},
+		{
+			name:     "rsvp",
+			shortcut: CalendarRsvp,
+			args:     []string{"+rsvp", "--event-id", "evt_rsvp1", "--rsvp-status", "accept"},
+		},
+		{
+			name:     "suggestion",
+			shortcut: CalendarSuggestion,
+			args:     []string{"+suggestion", "--start", "2025-03-21", "--end", "2025-03-21"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactory(t, noLoginConfig())
+
+			err := mountAndRun(t, tc.shortcut, tc.args, f, nil)
+			if err == nil {
+				t.Fatal("expected auth guard error")
+			}
+			if !strings.Contains(err.Error(), "auth login") {
+				t.Fatalf("expected auth login guidance, got: %v", err)
+			}
+			if !strings.Contains(err.Error(), "--as bot") {
+				t.Fatalf("expected explicit bot guidance, got: %v", err)
+			}
+		})
+	}
+}
+
+func TestAgenda_ExplicitBotBypassesLoginGuard(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, noLoginConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/events/instance_view",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarAgenda, []string{
+		"+agenda",
+		"--start", "2025-03-21",
+		"--end", "2025-03-21",
+		"--as", "bot",
+	}, f, stdout)
+
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestAgenda_DefaultAsBotBypassesLoginGuard(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, noLoginBotDefaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/events/instance_view",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarAgenda, []string{
+		"+agenda",
+		"--start", "2025-03-21",
+		"--end", "2025-03-21",
+	}, f, stdout)
+
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
 func TestAgenda_Success(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 
@@ -580,6 +695,118 @@ func TestFreebusy_APIError(t *testing.T) {
 // CalendarSuggestion tests
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// CalendarRsvp tests
+// ---------------------------------------------------------------------------
+
+func TestRsvp_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/evt_rsvp1/reply",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+		},
+	})
+
+	err := mountAndRun(t, CalendarRsvp, []string{
+		"+rsvp",
+		"--event-id", "evt_rsvp1",
+		"--rsvp-status", "accept",
+		"--as", "bot",
+	}, f, stdout)
+
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	for _, want := range []string{`"event_id": "evt_rsvp1"`, `"rsvp_status": "accept"`} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Errorf("stdout should contain %s, got: %s", want, stdout.String())
+		}
+	}
+}
+
+func TestRsvp_InvalidStatus(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	err := mountAndRun(t, CalendarRsvp, []string{
+		"+rsvp",
+		"--event-id", "evt_rsvp1",
+		"--rsvp-status", "invalid_status",
+		"--as", "bot",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected validation error for invalid status, got nil")
+	}
+	if !strings.Contains(err.Error(), "invalid value") {
+		t.Errorf("error should mention invalid value, got: %v", err)
+	}
+}
+
+func TestRsvp_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/evt_rsvp1/reply",
+		Body: map[string]interface{}{
+			"code": 190001,
+			"msg":  "permission denied",
+		},
+	})
+
+	err := mountAndRun(t, CalendarRsvp, []string{
+		"+rsvp",
+		"--event-id", "evt_rsvp1",
+		"--rsvp-status", "decline",
+		"--as", "bot",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected error for API failure, got nil")
+	}
+}
+
+func TestRsvp_RejectsDangerousChars(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	err := mountAndRun(t, CalendarRsvp, []string{
+		"+rsvp",
+		"--event-id", "evt_rsvp1\u202e",
+		"--rsvp-status", "accept",
+		"--as", "bot",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected validation error for dangerous characters, got nil")
+	}
+	if !strings.Contains(err.Error(), "dangerous Unicode") && !strings.Contains(err.Error(), "control character") {
+		t.Errorf("error should mention dangerous input, got: %v", err)
+	}
+}
+
+func TestRsvp_DryRun_TrimmedPrimaryCalendar(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	err := mountAndRun(t, CalendarRsvp, []string{
+		"+rsvp",
+		"--calendar-id", " primary ",
+		"--event-id", "evt_rsvp1",
+		"--rsvp-status", "accept",
+		"--dry-run",
+		"--as", "bot",
+	}, f, stdout)
+
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"calendar_id": "\u003cprimary\u003e"`) {
+		t.Errorf("dry-run should normalize primary calendar, got: %s", stdout.String())
+	}
+}
+
 func TestSuggestion_Success(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(&httpmock.Stub{
@@ -867,17 +1094,17 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) {
 // Shortcuts() registration test
 // ---------------------------------------------------------------------------
 
-func TestShortcuts_Returns4(t *testing.T) {
+func TestShortcuts_Returns5(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 4 {
-		t.Fatalf("expected 4 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 5 {
+		t.Fatalf("expected 5 shortcuts, got %d", len(shortcuts))
 	}
 
 	names := map[string]bool{}
 	for _, s := range shortcuts {
 		names[s.Command] = true
 	}
-	for _, want := range []string{"+agenda", "+create", "+freebusy", "+suggestion"} {
+	for _, want := range []string{"+agenda", "+create", "+freebusy", "+rsvp", "+suggestion"} {
 		if !names[want] {
 			t.Errorf("missing shortcut %s", want)
 		}