chore: release v1.0.4 (#253)

Update CHANGELOG.md and bump version to 1.0.4.

Change-Id: Ia0d65f4abf271dcff5563aac5ae81bcf4c4c6aea

.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

@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - "**.go"
+      - "!tests/cli_e2e/**"
       - go.mod
       - go.sum
       - .github/workflows/coverage.yml
@@ -12,6 +13,7 @@ on:
     branches: [main]
     paths:
       - "**.go"
+      - "!tests/cli_e2e/**"
       - go.mod
       - go.sum
       - .github/workflows/coverage.yml
@@ -37,7 +39,9 @@ jobs:
         run: python3 scripts/fetch_meta.py
 
       - name: Run tests with coverage
-        run: go test -race -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: Generate coverage report
         run: |

.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/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

@@ -7,7 +7,6 @@ on:
 
 permissions:
   contents: read
-  pull-requests: write
 
 jobs:
   publish:
@@ -31,51 +30,42 @@ jobs:
       - name: Publish to pkg.pr.new
         run: npx pkg-pr-new publish --no-compact --json output.json --comment=off ./.pkg-pr-new
 
-      - name: Comment install command
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+      - 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:
-          script: |
-            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");
-            }
-
-            const body = [
-              "Install this PR change globally:",
-              "",
-              "```bash",
-              `npm i -g ${url}`,
-              "```",
-            ].join("\n");
-            const issueNumber = context.issue.number;
-
-            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.startsWith("Install this PR change globally:")
-            );
-
-            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,
-              });
-            }
+          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/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

.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"]

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,80 @@
 
 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
@@ -87,5 +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

README.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-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 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
@@ -22,19 +22,20 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 
 ## 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                      |
+| 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                          |
+| 📈 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
 
@@ -127,27 +128,28 @@ 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
 

README.zh.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 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 调用只需三步
@@ -22,19 +22,20 @@
 
 ## 功能
 
-| 类别        | 能力                                                                      |
-| ------------- | --------------------------------------------------------------------------- |
-| 📅 日历     | 查看日程、创建日程、邀请参会人、查询忙闲状态、时间建议                    |
-| 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件 |
-| 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                            |
-| 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                                |
+| 类别        | 能力                                         |
+| ------------- |--------------------------------------------|
+| 📅 日历     | 查看日程、创建日程、邀请参会人、查询忙闲状态、时间建议                |
+| 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件      |
+| 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                    |
+| 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                      |
 | 📊 多维表格 | 创建和管理数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限，数据聚合分析 |
-| 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                                |
-| ✅ 任务     | 创建、查询、更新和完成任务；管理任务清单、子任务、评论与提醒              |
-| 📚 知识库   | 创建和管理知识空间、节点和文档                                            |
-| 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                                  |
-| 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件          |
-| 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                                          |
+| 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据                      |
+| ✅ 任务     | 创建、查询、更新和完成任务；管理任务清单、子任务、评论与提醒             |
+| 📚 知识库   | 创建和管理知识空间、节点和文档                            |
+| 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                      |
+| 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件           |
+| 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                           |
+| ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 
 ## 安装与快速开始
 
@@ -128,27 +129,28 @@ 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`  | 工作流：日程待办摘要                                |
 
 ## 认证
 

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,6 +200,7 @@ 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,
 	})
@@ -210,7 +216,15 @@ func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.Cl
 	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

@@ -536,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/root.go

@@ -4,6 +4,7 @@
 package cmd
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -60,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:
@@ -241,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/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/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/registry/service_descriptions.json

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

internal/update/update.go

@@ -17,6 +17,7 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -57,7 +58,10 @@ func httpClient() *http.Client {
 	if DefaultClient != nil {
 		return DefaultClient
 	}
-	return &http.Client{Timeout: fetchTimeout}
+	return &http.Client{
+		Timeout:   fetchTimeout,
+		Transport: util.NewBaseTransport(),
+	}
 }
 
 // updateState is persisted to disk for caching.

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.1",
+  "version": "1.0.4",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

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/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/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

@@ -46,6 +46,9 @@ var CalendarRsvp = common.Shortcut{
 			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 {

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())
 

shortcuts/calendar/helpers.go

@@ -4,9 +4,12 @@
 package calendar
 
 import (
+	"strings"
 	"time"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
 const (
@@ -26,3 +29,24 @@ func resolveStartEnd(runtime *common.RuntimeContext) (string, string) {
 	}
 	return startInput, endInput
 }
+
+func hasExplicitBotFlag(cmd *cobra.Command) bool {
+	if cmd == nil {
+		return false
+	}
+	flag := cmd.Flag("as")
+	return flag != nil && flag.Changed && flag.Value != nil && strings.TrimSpace(flag.Value.String()) == "bot"
+}
+
+func rejectCalendarAutoBotFallback(runtime *common.RuntimeContext) error {
+	if runtime == nil || !runtime.IsBot() || hasExplicitBotFlag(runtime.Cmd) {
+		return nil
+	}
+	if runtime.Factory == nil || !runtime.Factory.IdentityAutoDetected {
+		return nil
+	}
+
+	msg := "calendar commands require a valid user login by default; when no valid user login state is available, auto identity falls back to bot and may operate on the bot calendar instead of your own. Run `lark-cli auth login --domain calendar` for your calendar, or rerun with `--as bot` if bot identity is intentional."
+	hint := "restore user login: `lark-cli auth login --domain calendar`\nintentional bot usage: rerun with `--as bot`"
+	return output.ErrWithHint(output.ExitAuth, "calendar_user_login_required", msg, hint)
+}

shortcuts/common/runner.go

@@ -33,6 +33,8 @@ type RuntimeContext struct {
 	Config     *core.CliConfig
 	Cmd        *cobra.Command
 	Format     string
+	JqExpr     string            // --jq expression; empty = no filter
+	outputErr  error             // deferred error from Out()/OutFormat() jq filtering
 	botOnly    bool              // set by framework for bot-only shortcuts
 	resolvedAs core.Identity     // effective identity resolved by framework
 	Factory    *cmdutil.Factory  // injected by framework
@@ -225,6 +227,20 @@ func (ctx *RuntimeContext) DoAPI(req *larkcore.ApiReq, opts ...larkcore.RequestO
 	return ac.DoSDKRequest(ctx.ctx, req, ctx.As(), opts...)
 }
 
+// DoAPIAsBot executes a raw Lark SDK request using bot identity (tenant access token),
+// regardless of the current --as flag. Use this for bot-only APIs (e.g. image/file upload)
+// that must be called with TAT even when the surrounding shortcut runs as user.
+func (ctx *RuntimeContext) DoAPIAsBot(req *larkcore.ApiReq, opts ...larkcore.RequestOptionFunc) (*larkcore.ApiResp, error) {
+	ac, err := ctx.getAPIClient()
+	if err != nil {
+		return nil, err
+	}
+	if optFn := cmdutil.ShortcutHeaderOpts(ctx.ctx); optFn != nil {
+		opts = append(opts, optFn)
+	}
+	return ac.DoSDKRequest(ctx.ctx, req, core.AsBot, opts...)
+}
+
 type cancelOnCloseReadCloser struct {
 	io.ReadCloser
 	cancel context.CancelFunc
@@ -419,13 +435,27 @@ func (ctx *RuntimeContext) IO() *cmdutil.IOStreams {
 // Out prints a success JSON envelope to stdout.
 func (ctx *RuntimeContext) Out(data interface{}, meta *output.Meta) {
 	env := output.Envelope{OK: true, Identity: string(ctx.As()), Data: data, Meta: meta, Notice: output.GetNotice()}
+	if ctx.JqExpr != "" {
+		if err := output.JqFilter(ctx.IO().Out, env, ctx.JqExpr); err != nil {
+			fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err)
+			if ctx.outputErr == nil {
+				ctx.outputErr = err
+			}
+		}
+		return
+	}
 	b, _ := json.MarshalIndent(env, "", "  ")
 	fmt.Fprintln(ctx.IO().Out, string(b))
 }
 
 // OutFormat prints output based on --format flag.
 // "json" (default) outputs JSON envelope; "pretty" calls prettyFn; others delegate to FormatValue.
+// When JqExpr is set, routes through Out() regardless of format.
 func (ctx *RuntimeContext) OutFormat(data interface{}, meta *output.Meta, prettyFn func(w io.Writer)) {
+	if ctx.JqExpr != "" {
+		ctx.Out(data, meta)
+		return
+	}
 	switch ctx.Format {
 	case "pretty":
 		if prettyFn != nil {
@@ -546,6 +576,9 @@ func runShortcut(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, botOnly bo
 	if err := validateEnumFlags(rctx, s.Flags); err != nil {
 		return err
 	}
+	if err := output.ValidateJqFlags(rctx.JqExpr, "", rctx.Format); err != nil {
+		return err
+	}
 	if s.Validate != nil {
 		if err := s.Validate(rctx.ctx, rctx); err != nil {
 			return err
@@ -562,7 +595,10 @@ func runShortcut(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, botOnly bo
 		}
 	}
 
-	return s.Execute(rctx.ctx, rctx)
+	if err := s.Execute(rctx.ctx, rctx); err != nil {
+		return err
+	}
+	return rctx.outputErr
 }
 
 func resolveShortcutIdentity(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) (core.Identity, error) {
@@ -604,6 +640,7 @@ func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, conf
 	if s.HasFormat {
 		rctx.Format = rctx.Str("format")
 	}
+	rctx.JqExpr, _ = cmd.Flags().GetString("jq")
 	return rctx, nil
 }
 
@@ -684,6 +721,7 @@ func registerShortcutFlags(cmd *cobra.Command, s *Shortcut) {
 	if s.Risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}
+	cmd.Flags().StringP("jq", "q", "", "jq expression to filter JSON output")
 	cmd.Flags().String("as", s.AuthTypes[0], "identity type: user | bot")
 
 	_ = cmd.RegisterFlagCompletionFunc("as", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {

shortcuts/common/runner_jq_test.go

@@ -0,0 +1,201 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"strings"
+	"testing"
+
+	lark "github.com/larksuite/oapi-sdk-go/v3"
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// newJqTestContext creates a RuntimeContext wired for jq testing.
+func newJqTestContext(jqExpr, format string) (*RuntimeContext, *bytes.Buffer, *bytes.Buffer) {
+	stdout := &bytes.Buffer{}
+	stderr := &bytes.Buffer{}
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("jq", "", "")
+	cmd.Flags().String("format", "json", "")
+	cmd.Flags().String("as", "bot", "")
+	cmd.ParseFlags(nil)
+	if jqExpr != "" {
+		cmd.Flags().Set("jq", jqExpr)
+	}
+	if format != "" {
+		cmd.Flags().Set("format", format)
+	}
+
+	rctx := &RuntimeContext{
+		ctx:        context.Background(),
+		Config:     &core.CliConfig{Brand: core.BrandFeishu},
+		Cmd:        cmd,
+		Format:     format,
+		JqExpr:     jqExpr,
+		resolvedAs: core.AsBot,
+		Factory: &cmdutil.Factory{
+			IOStreams: &cmdutil.IOStreams{Out: stdout, ErrOut: stderr},
+		},
+	}
+	return rctx, stdout, stderr
+}
+
+func TestRuntimeContext_Out_WithJq(t *testing.T) {
+	rctx, stdout, _ := newJqTestContext(".data.name", "")
+
+	rctx.Out(map[string]interface{}{
+		"name": "Alice",
+		"age":  30,
+	}, nil)
+
+	out := stdout.String()
+	if !strings.Contains(out, "Alice") {
+		t.Errorf("expected jq-filtered 'Alice', got: %s", out)
+	}
+	if strings.Contains(out, "age") {
+		t.Errorf("expected jq to filter out 'age', got: %s", out)
+	}
+}
+
+func TestRuntimeContext_Out_WithJq_Identity(t *testing.T) {
+	rctx, stdout, _ := newJqTestContext(".ok", "")
+
+	rctx.Out(map[string]interface{}{"key": "value"}, nil)
+
+	out := strings.TrimSpace(stdout.String())
+	if out != "true" {
+		t.Errorf("expected 'true' for .ok, got: %s", out)
+	}
+}
+
+func TestRuntimeContext_OutFormat_WithJq_OverridesFormat(t *testing.T) {
+	rctx, stdout, _ := newJqTestContext(".data.items", "pretty")
+
+	items := []interface{}{"a", "b", "c"}
+	rctx.OutFormat(map[string]interface{}{
+		"items": items,
+	}, nil, func(w io.Writer) {
+		t.Error("prettyFn should not be called when jq is set")
+	})
+
+	out := stdout.String()
+	if !strings.Contains(out, "a") || !strings.Contains(out, "b") {
+		t.Errorf("expected jq-filtered items, got: %s", out)
+	}
+}
+
+func TestRuntimeContext_Out_WithJq_InvalidExpr_WritesStderr(t *testing.T) {
+	rctx, _, stderr := newJqTestContext(".foo | invalid_func_xyz", "")
+
+	rctx.Out(map[string]interface{}{"foo": "bar"}, nil)
+
+	if !strings.Contains(stderr.String(), "error") {
+		t.Errorf("expected error on stderr for runtime jq error, got: %s", stderr.String())
+	}
+}
+
+func newTestShortcutCmd(s *Shortcut) *cobra.Command {
+	cmd := &cobra.Command{Use: "test-shortcut"}
+	cmd.SetContext(context.Background())
+	registerShortcutFlags(cmd, s)
+	return cmd
+}
+
+func newTestFactory() *cmdutil.Factory {
+	return &cmdutil.Factory{
+		Config: func() (*core.CliConfig, error) {
+			return &core.CliConfig{
+				AppID: "test", AppSecret: "test", Brand: core.BrandFeishu,
+			}, nil
+		},
+		LarkClient: func() (*lark.Client, error) {
+			return lark.NewClient("test", "test"), nil
+		},
+		IOStreams: &cmdutil.IOStreams{Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{}},
+	}
+}
+
+func TestRunShortcut_JqAndFormatConflict(t *testing.T) {
+	s := &Shortcut{
+		Service:   "test",
+		Command:   "test-shortcut",
+		AuthTypes: []string{"bot"},
+		HasFormat: true,
+		Execute: func(ctx context.Context, rctx *RuntimeContext) error {
+			return nil
+		},
+	}
+	cmd := newTestShortcutCmd(s)
+	cmd.Flags().Set("jq", ".data")
+	cmd.Flags().Set("format", "table")
+	cmd.Flags().Set("as", "bot")
+
+	err := runShortcut(cmd, newTestFactory(), s, true)
+	if err == nil {
+		t.Fatal("expected error for --jq + --format table conflict")
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Errorf("expected 'mutually exclusive' error, got: %v", err)
+	}
+}
+
+func TestRunShortcut_JqInvalidExpression(t *testing.T) {
+	s := &Shortcut{
+		Service:   "test",
+		Command:   "test-shortcut",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *RuntimeContext) error {
+			return nil
+		},
+	}
+	cmd := newTestShortcutCmd(s)
+	cmd.Flags().Set("jq", "invalid[")
+	cmd.Flags().Set("as", "bot")
+
+	err := runShortcut(cmd, newTestFactory(), s, true)
+	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 TestRunShortcut_JqRuntimeError_PropagatesError(t *testing.T) {
+	s := &Shortcut{
+		Service:   "test",
+		Command:   "test-shortcut",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *RuntimeContext) error {
+			rctx.Out(map[string]interface{}{"foo": "bar"}, nil)
+			return nil
+		},
+	}
+	cmd := newTestShortcutCmd(s)
+	cmd.Flags().Set("jq", ".foo | invalid_func_xyz")
+	cmd.Flags().Set("as", "bot")
+
+	err := runShortcut(cmd, newTestFactory(), s, true)
+	if err == nil {
+		t.Fatal("expected error from jq runtime failure to propagate")
+	}
+}
+
+func TestRuntimeContext_Out_WithoutJq_NormalOutput(t *testing.T) {
+	rctx, stdout, _ := newJqTestContext("", "")
+
+	rctx.Out(map[string]interface{}{"key": "value"}, &output.Meta{Count: 1})
+
+	out := stdout.String()
+	if !strings.Contains(out, `"ok"`) || !strings.Contains(out, `"key"`) {
+		t.Errorf("expected normal JSON envelope, got: %s", out)
+	}
+}

shortcuts/common/testing.go

@@ -22,3 +22,8 @@ func TestNewRuntimeContext(cmd *cobra.Command, cfg *core.CliConfig) *RuntimeCont
 func TestNewRuntimeContextWithCtx(ctx context.Context, cmd *cobra.Command, cfg *core.CliConfig) *RuntimeContext {
 	return &RuntimeContext{ctx: ctx, Cmd: cmd, Config: cfg}
 }
+
+// TestNewRuntimeContextWithIdentity creates a RuntimeContext with a specific identity for testing.
+func TestNewRuntimeContextWithIdentity(cmd *cobra.Command, cfg *core.CliConfig, as core.Identity) *RuntimeContext {
+	return &RuntimeContext{Cmd: cmd, Config: cfg, resolvedAs: as}
+}

shortcuts/drive/drive_export.go

@@ -0,0 +1,245 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// DriveExport exports Drive-native documents to local files and falls back to
+// a follow-up command when the async export task does not finish in time.
+var DriveExport = common.Shortcut{
+	Service:     "drive",
+	Command:     "+export",
+	Description: "Export a doc/docx/sheet/bitable to a local file with limited polling",
+	Risk:        "read",
+	Scopes: []string{
+		"docs:document.content:read",
+		"docs:document:export",
+		"drive:drive.metadata:readonly",
+	},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "token", Desc: "source document token", Required: true},
+		{Name: "doc-type", Desc: "source document type: doc | docx | sheet | bitable", Required: true, Enum: []string{"doc", "docx", "sheet", "bitable"}},
+		{Name: "file-extension", Desc: "export format: docx | pdf | xlsx | csv | markdown", Required: true, Enum: []string{"docx", "pdf", "xlsx", "csv", "markdown"}},
+		{Name: "sub-id", Desc: "sub-table/sheet ID, required when exporting sheet/bitable as csv"},
+		{Name: "output-dir", Default: ".", Desc: "local output directory (default: current directory)"},
+		{Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateDriveExportSpec(driveExportSpec{
+			Token:         runtime.Str("token"),
+			DocType:       runtime.Str("doc-type"),
+			FileExtension: runtime.Str("file-extension"),
+			SubID:         runtime.Str("sub-id"),
+		})
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec := driveExportSpec{
+			Token:         runtime.Str("token"),
+			DocType:       runtime.Str("doc-type"),
+			FileExtension: runtime.Str("file-extension"),
+			SubID:         runtime.Str("sub-id"),
+		}
+		// Markdown export is a special case: docx markdown comes from docs content
+		// directly instead of the Drive export task API.
+		if spec.FileExtension == "markdown" {
+			return common.NewDryRunAPI().
+				Desc("2-step orchestration: fetch docx markdown -> write local file").
+				GET("/open-apis/docs/v1/content").
+				Params(map[string]interface{}{
+					"doc_token":    spec.Token,
+					"doc_type":     "docx",
+					"content_type": "markdown",
+				})
+		}
+
+		body := map[string]interface{}{
+			"token":          spec.Token,
+			"type":           spec.DocType,
+			"file_extension": spec.FileExtension,
+		}
+		if strings.TrimSpace(spec.SubID) != "" {
+			body["sub_id"] = spec.SubID
+		}
+
+		return common.NewDryRunAPI().
+			Desc("3-step orchestration: create export task -> limited polling -> download file").
+			POST("/open-apis/drive/v1/export_tasks").
+			Body(body)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := driveExportSpec{
+			Token:         runtime.Str("token"),
+			DocType:       runtime.Str("doc-type"),
+			FileExtension: runtime.Str("file-extension"),
+			SubID:         runtime.Str("sub-id"),
+		}
+		outputDir := runtime.Str("output-dir")
+		overwrite := runtime.Bool("overwrite")
+
+		// Markdown export bypasses the async export task and writes the fetched
+		// markdown content directly to disk.
+		if spec.FileExtension == "markdown" {
+			fmt.Fprintf(runtime.IO().ErrOut, "Exporting docx as markdown: %s\n", common.MaskToken(spec.Token))
+			data, err := runtime.CallAPI(
+				"GET",
+				"/open-apis/docs/v1/content",
+				map[string]interface{}{
+					"doc_token":    spec.Token,
+					"doc_type":     "docx",
+					"content_type": "markdown",
+				},
+				nil,
+			)
+			if err != nil {
+				return err
+			}
+
+			// Prefer the remote title for the exported file name, but still fall
+			// back to the token if metadata is empty.
+			title, err := fetchDriveMetaTitle(runtime, spec.Token, spec.DocType)
+			if err != nil {
+				fmt.Fprintf(runtime.IO().ErrOut, "Title lookup failed, using token as filename: %v\n", err)
+				title = spec.Token
+			}
+			fileName := ensureExportFileExtension(sanitizeExportFileName(title, spec.Token), spec.FileExtension)
+			savedPath, err := saveContentToOutputDir(outputDir, fileName, []byte(common.GetString(data, "content")), overwrite)
+			if err != nil {
+				return err
+			}
+
+			runtime.Out(map[string]interface{}{
+				"token":          spec.Token,
+				"doc_type":       spec.DocType,
+				"file_extension": spec.FileExtension,
+				"file_name":      filepath.Base(savedPath),
+				"saved_path":     savedPath,
+				"size_bytes":     len([]byte(common.GetString(data, "content"))),
+			}, nil)
+			return nil
+		}
+
+		ticket, err := createDriveExportTask(runtime, spec)
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "Created export task: %s\n", ticket)
+
+		var lastStatus driveExportStatus
+		var lastPollErr error
+		hasObservedStatus := false
+		// Keep the command responsive by polling for a bounded window. If the task
+		// is still running after that, return a resume command instead of blocking.
+		for attempt := 1; attempt <= driveExportPollAttempts; attempt++ {
+			if attempt > 1 {
+				select {
+				case <-ctx.Done():
+					return ctx.Err()
+				case <-time.After(driveExportPollInterval):
+				}
+			}
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+
+			status, err := getDriveExportStatus(runtime, spec.Token, ticket)
+			if err != nil {
+				// Treat polling failures as transient so short-lived backend hiccups
+				// do not immediately fail an otherwise healthy export task.
+				lastPollErr = err
+				fmt.Fprintf(runtime.IO().ErrOut, "Export status attempt %d/%d failed: %v\n", attempt, driveExportPollAttempts, err)
+				continue
+			}
+			lastStatus = status
+			hasObservedStatus = true
+
+			if status.Ready() {
+				fmt.Fprintf(runtime.IO().ErrOut, "Export task completed: %s\n", common.MaskToken(status.FileToken))
+				fileName := ensureExportFileExtension(sanitizeExportFileName(status.FileName, spec.Token), spec.FileExtension)
+				out, err := downloadDriveExportFile(ctx, runtime, status.FileToken, outputDir, fileName, overwrite)
+				if err != nil {
+					recoveryCommand := driveExportDownloadCommand(status.FileToken, fileName, outputDir, overwrite)
+					hint := fmt.Sprintf(
+						"the export artifact is already ready (ticket=%s, file_token=%s)\nretry download with: %s",
+						ticket,
+						status.FileToken,
+						recoveryCommand,
+					)
+					var exitErr *output.ExitError
+					if errors.As(err, &exitErr) && exitErr.Detail != nil {
+						return output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message, hint)
+					}
+					return output.ErrWithHint(output.ExitAPI, "api_error", err.Error(), hint)
+				}
+				out["ticket"] = ticket
+				out["doc_type"] = spec.DocType
+				out["file_extension"] = spec.FileExtension
+				runtime.Out(out, nil)
+				return nil
+			}
+
+			if status.Failed() {
+				msg := strings.TrimSpace(status.JobErrorMsg)
+				if msg == "" {
+					msg = status.StatusLabel()
+				}
+				return output.Errorf(output.ExitAPI, "api_error", "export task failed: %s (ticket=%s)", msg, ticket)
+			}
+
+			fmt.Fprintf(runtime.IO().ErrOut, "Export status %d/%d: %s\n", attempt, driveExportPollAttempts, status.StatusLabel())
+		}
+
+		nextCommand := driveExportTaskResultCommand(ticket, spec.Token)
+		if !hasObservedStatus && lastPollErr != nil {
+			hint := fmt.Sprintf(
+				"the export task was created but every status poll failed (ticket=%s)\nretry status lookup with: %s",
+				ticket,
+				nextCommand,
+			)
+			var exitErr *output.ExitError
+			if errors.As(lastPollErr, &exitErr) && exitErr.Detail != nil {
+				if strings.TrimSpace(exitErr.Detail.Hint) != "" {
+					hint = exitErr.Detail.Hint + "\n" + hint
+				}
+				return output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message, hint)
+			}
+			return output.ErrWithHint(output.ExitAPI, "api_error", lastPollErr.Error(), hint)
+		}
+
+		failed := false
+		var jobStatus interface{}
+		jobStatusLabel := "unknown"
+		if hasObservedStatus {
+			failed = lastStatus.Failed()
+			jobStatus = lastStatus.JobStatus
+			jobStatusLabel = lastStatus.StatusLabel()
+		}
+		// Return the last observed status so callers can resume from a known task
+		// state instead of losing all progress information on timeout.
+		runtime.Out(map[string]interface{}{
+			"ticket":           ticket,
+			"token":            spec.Token,
+			"doc_type":         spec.DocType,
+			"file_extension":   spec.FileExtension,
+			"ready":            false,
+			"failed":           failed,
+			"job_status":       jobStatus,
+			"job_status_label": jobStatusLabel,
+			"timed_out":        true,
+			"next_command":     nextCommand,
+		}, nil)
+		fmt.Fprintf(runtime.IO().ErrOut, "Export task is still in progress. Continue with: %s\n", nextCommand)
+		return nil
+	},
+}

shortcuts/drive/drive_export_common.go

@@ -0,0 +1,371 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/client"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var (
+	driveExportPollAttempts = 10
+	driveExportPollInterval = 5 * time.Second
+)
+
+// driveExportSpec contains the normalized export request understood by the
+// shortcut and the underlying export task APIs.
+type driveExportSpec struct {
+	Token         string
+	DocType       string
+	FileExtension string
+	SubID         string
+}
+
+// driveExportTaskResultCommand prints the resume command shown when bounded
+// export polling times out locally.
+func driveExportTaskResultCommand(ticket, docToken string) string {
+	return fmt.Sprintf("lark-cli drive +task_result --scenario export --ticket %s --file-token %s", ticket, docToken)
+}
+
+// driveExportDownloadCommand prints a copy-pasteable follow-up command for
+// downloading an already-generated export artifact by file token.
+func driveExportDownloadCommand(fileToken, fileName, outputDir string, overwrite bool) string {
+	parts := []string{
+		"lark-cli", "drive", "+export-download",
+		"--file-token", strconv.Quote(fileToken),
+	}
+	if strings.TrimSpace(fileName) != "" {
+		parts = append(parts, "--file-name", strconv.Quote(fileName))
+	}
+	if strings.TrimSpace(outputDir) != "" && outputDir != "." {
+		parts = append(parts, "--output-dir", strconv.Quote(outputDir))
+	}
+	if overwrite {
+		parts = append(parts, "--overwrite")
+	}
+	return strings.Join(parts, " ")
+}
+
+// driveExportStatus captures the fields needed to decide whether the export is
+// ready for download, still pending, or terminally failed.
+type driveExportStatus struct {
+	Ticket        string
+	FileExtension string
+	DocType       string
+	FileName      string
+	FileToken     string
+	JobErrorMsg   string
+	FileSize      int64
+	JobStatus     int
+}
+
+func (s driveExportStatus) Ready() bool {
+	return s.FileToken != "" && s.JobStatus == 0
+}
+
+func (s driveExportStatus) Pending() bool {
+	// A zero status without a file token is still in progress because there is
+	// nothing downloadable yet.
+	return s.JobStatus == 1 || s.JobStatus == 2 || s.JobStatus == 0 && s.FileToken == ""
+}
+
+func (s driveExportStatus) Failed() bool {
+	return !s.Ready() && !s.Pending() && s.JobStatus != 0
+}
+
+func (s driveExportStatus) StatusLabel() string {
+	switch s.JobStatus {
+	case 0:
+		// Success is a special case where the file token is set.
+		if s.FileToken != "" {
+			return "success"
+		}
+		return "pending"
+	case 1:
+		return "new"
+	case 2:
+		return "processing"
+	case 3:
+		return "internal_error"
+	case 107:
+		return "export_size_limit"
+	case 108:
+		return "timeout"
+	case 109:
+		return "export_block_not_permitted"
+	case 110:
+		return "no_permission"
+	case 111:
+		return "docs_deleted"
+	case 122:
+		return "export_denied_on_copying"
+	case 123:
+		return "docs_not_exist"
+	case 6000:
+		return "export_images_exceed_limit"
+	default:
+		return fmt.Sprintf("status_%d", s.JobStatus)
+	}
+}
+
+// validateDriveExportSpec enforces shortcut-level export constraints before any
+// backend request is sent.
+func validateDriveExportSpec(spec driveExportSpec) error {
+	if err := validate.ResourceName(spec.Token, "--token"); err != nil {
+		return output.ErrValidation("%s", err)
+	}
+
+	switch spec.DocType {
+	case "doc", "docx", "sheet", "bitable":
+	default:
+		return output.ErrValidation("invalid --doc-type %q: allowed values are doc, docx, sheet, bitable", spec.DocType)
+	}
+
+	switch spec.FileExtension {
+	case "docx", "pdf", "xlsx", "csv", "markdown":
+	default:
+		return output.ErrValidation("invalid --file-extension %q: allowed values are docx, pdf, xlsx, csv, markdown", spec.FileExtension)
+	}
+
+	if spec.FileExtension == "markdown" && spec.DocType != "docx" {
+		return output.ErrValidation("--file-extension markdown only supports --doc-type docx")
+	}
+
+	if strings.TrimSpace(spec.SubID) != "" {
+		if spec.FileExtension != "csv" || (spec.DocType != "sheet" && spec.DocType != "bitable") {
+			return output.ErrValidation("--sub-id is only used when exporting sheet/bitable as csv")
+		}
+		if err := validate.ResourceName(spec.SubID, "--sub-id"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+	}
+
+	if spec.FileExtension == "csv" && (spec.DocType == "sheet" || spec.DocType == "bitable") && strings.TrimSpace(spec.SubID) == "" {
+		return output.ErrValidation("--sub-id is required when exporting sheet/bitable as csv")
+	}
+
+	return nil
+}
+
+// createDriveExportTask starts the asynchronous export job and returns its
+// ticket for subsequent polling.
+func createDriveExportTask(runtime *common.RuntimeContext, spec driveExportSpec) (string, error) {
+	body := map[string]interface{}{
+		"token":          spec.Token,
+		"type":           spec.DocType,
+		"file_extension": spec.FileExtension,
+	}
+	if strings.TrimSpace(spec.SubID) != "" {
+		body["sub_id"] = spec.SubID
+	}
+
+	data, err := runtime.CallAPI("POST", "/open-apis/drive/v1/export_tasks", nil, body)
+	if err != nil {
+		return "", err
+	}
+
+	ticket := common.GetString(data, "ticket")
+	if ticket == "" {
+		return "", output.Errorf(output.ExitAPI, "api_error", "export task created but ticket is missing")
+	}
+	return ticket, nil
+}
+
+// getDriveExportStatus fetches the current backend state for a previously
+// created export task.
+func getDriveExportStatus(runtime *common.RuntimeContext, token, ticket string) (driveExportStatus, error) {
+	data, err := runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/drive/v1/export_tasks/%s", validate.EncodePathSegment(ticket)),
+		map[string]interface{}{"token": token},
+		nil,
+	)
+	if err != nil {
+		return driveExportStatus{}, err
+	}
+	return parseDriveExportStatus(ticket, data), nil
+}
+
+// parseDriveExportStatus accepts the wrapped export result and normalizes the
+// subset of fields used by the shortcut.
+func parseDriveExportStatus(ticket string, data map[string]interface{}) driveExportStatus {
+	result := common.GetMap(data, "result")
+	status := driveExportStatus{
+		Ticket: ticket,
+	}
+	if result == nil {
+		// Keep the ticket even when the result body is missing so callers can
+		// still show a resumable task reference.
+		return status
+	}
+
+	status.FileExtension = common.GetString(result, "file_extension")
+	status.DocType = common.GetString(result, "type")
+	status.FileName = common.GetString(result, "file_name")
+	status.FileToken = common.GetString(result, "file_token")
+	status.JobErrorMsg = common.GetString(result, "job_error_msg")
+	status.FileSize = int64(common.GetFloat(result, "file_size"))
+	status.JobStatus = int(common.GetFloat(result, "job_status"))
+	return status
+}
+
+// fetchDriveMetaTitle looks up the document title so exported files can use a
+// human-readable default name when possible.
+func fetchDriveMetaTitle(runtime *common.RuntimeContext, token, docType string) (string, error) {
+	data, err := runtime.CallAPI(
+		"POST",
+		"/open-apis/drive/v1/metas/batch_query",
+		nil,
+		map[string]interface{}{
+			"request_docs": []map[string]interface{}{
+				{
+					"doc_token": token,
+					"doc_type":  docType,
+				},
+			},
+		},
+	)
+	if err != nil {
+		return "", err
+	}
+
+	metas := common.GetSlice(data, "metas")
+	if len(metas) == 0 {
+		return "", nil
+	}
+	meta, _ := metas[0].(map[string]interface{})
+	return common.GetString(meta, "title"), nil
+}
+
+// saveContentToOutputDir validates the target path, enforces overwrite policy,
+// and writes the payload atomically to disk.
+func saveContentToOutputDir(outputDir, fileName string, payload []byte, overwrite bool) (string, error) {
+	if outputDir == "" {
+		outputDir = "."
+	}
+
+	// Sanitize both the filename and the combined output path so caller-provided
+	// names cannot escape the requested output directory.
+	safeName := sanitizeExportFileName(fileName, "export.bin")
+	target := filepath.Join(outputDir, safeName)
+	safePath, err := validate.SafeOutputPath(target)
+	if err != nil {
+		return "", output.ErrValidation("unsafe output path: %s", err)
+	}
+	if err := common.EnsureWritableFile(safePath, overwrite); err != nil {
+		return "", err
+	}
+
+	if err := os.MkdirAll(filepath.Dir(safePath), 0755); err != nil {
+		return "", output.Errorf(output.ExitInternal, "io", "cannot create output directory: %s", err)
+	}
+	if err := validate.AtomicWrite(safePath, payload, 0644); err != nil {
+		return "", output.Errorf(output.ExitInternal, "io", "cannot write file: %s", err)
+	}
+	return safePath, nil
+}
+
+// downloadDriveExportFile downloads the exported artifact, derives a safe local
+// file name, and returns metadata about the saved file.
+func downloadDriveExportFile(ctx context.Context, runtime *common.RuntimeContext, fileToken, outputDir, preferredName string, overwrite bool) (map[string]interface{}, error) {
+	if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
+		return nil, output.ErrValidation("%s", err)
+	}
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/export_tasks/file/%s/download", validate.EncodePathSegment(fileToken)),
+	}, larkcore.WithFileDownload())
+	if err != nil {
+		return nil, output.ErrNetwork("download failed: %s", err)
+	}
+	if apiResp.StatusCode >= 400 {
+		return nil, output.ErrNetwork("download failed: HTTP %d: %s", apiResp.StatusCode, string(apiResp.RawBody))
+	}
+
+	fileName := strings.TrimSpace(preferredName)
+	if fileName == "" {
+		// Fall back to the server-provided download name when the caller did not
+		// request an explicit local file name.
+		fileName = client.ResolveFilename(apiResp)
+	}
+	savedPath, err := saveContentToOutputDir(outputDir, fileName, apiResp.RawBody, overwrite)
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]interface{}{
+		"file_token":   fileToken,
+		"file_name":    filepath.Base(savedPath),
+		"saved_path":   savedPath,
+		"size_bytes":   len(apiResp.RawBody),
+		"content_type": apiResp.Header.Get("Content-Type"),
+	}, nil
+}
+
+// sanitizeExportFileName strips path traversal and unsupported characters while
+// preserving a readable file name when possible.
+func sanitizeExportFileName(name, fallback string) string {
+	name = strings.TrimSpace(filepath.Base(name))
+	if name == "" || name == "." || name == string(filepath.Separator) {
+		name = fallback
+	}
+
+	replacer := strings.NewReplacer(
+		"/", "_", "\\", "_", ":", "_", "*", "_", "?", "_",
+		"\"", "_", "<", "_", ">", "_", "|", "_",
+		"\n", "_", "\r", "_", "\t", "_", "\x00", "_",
+	)
+	name = replacer.Replace(name)
+	name = strings.Trim(name, ". ")
+	if name == "" {
+		return fallback
+	}
+	return name
+}
+
+// ensureExportFileExtension appends the expected local suffix when the chosen
+// file name does not already end with the export format's extension.
+func ensureExportFileExtension(name, fileExtension string) string {
+	expected := exportFileSuffix(fileExtension)
+	if expected == "" {
+		return name
+	}
+	if strings.EqualFold(filepath.Ext(name), expected) {
+		return name
+	}
+	return name + expected
+}
+
+// exportFileSuffix maps shortcut-level export formats to the local filename
+// suffix written to disk.
+func exportFileSuffix(fileExtension string) string {
+	switch fileExtension {
+	case "markdown":
+		return ".md"
+	case "docx":
+		return ".docx"
+	case "pdf":
+		return ".pdf"
+	case "xlsx":
+		return ".xlsx"
+	case "csv":
+		return ".csv"
+	default:
+		return ""
+	}
+}

shortcuts/drive/drive_export_common_test.go

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import "testing"
+
+func TestDriveExportStatusLabelCoversKnownAndUnknownCodes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		status driveExportStatus
+		want   string
+	}{
+		{
+			name:   "size limit",
+			status: driveExportStatus{JobStatus: 107},
+			want:   "export_size_limit",
+		},
+		{
+			name:   "not exist",
+			status: driveExportStatus{JobStatus: 123},
+			want:   "docs_not_exist",
+		},
+		{
+			name:   "unknown status",
+			status: driveExportStatus{JobStatus: 999},
+			want:   "status_999",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := tt.status.StatusLabel(); got != tt.want {
+				t.Fatalf("StatusLabel() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseDriveExportStatusWithoutResultKeepsTicket(t *testing.T) {
+	t.Parallel()
+
+	status := parseDriveExportStatus("ticket_export_test", map[string]interface{}{})
+	if status.Ticket != "ticket_export_test" {
+		t.Fatalf("ticket = %q, want %q", status.Ticket, "ticket_export_test")
+	}
+	if status.FileToken != "" {
+		t.Fatalf("file token = %q, want empty", status.FileToken)
+	}
+}
+
+func TestSanitizeExportFileNameAndEnsureExtension(t *testing.T) {
+	t.Parallel()
+
+	if got := sanitizeExportFileName("../quarterly:report?.pdf", "fallback.bin"); got != "quarterly_report_.pdf" {
+		t.Fatalf("sanitizeExportFileName() = %q, want %q", got, "quarterly_report_.pdf")
+	}
+	if got := ensureExportFileExtension("meeting-notes", "markdown"); got != "meeting-notes.md" {
+		t.Fatalf("ensureExportFileExtension() = %q, want %q", got, "meeting-notes.md")
+	}
+	if got := ensureExportFileExtension("report.pdf", "pdf"); got != "report.pdf" {
+		t.Fatalf("ensureExportFileExtension() should preserve suffix, got %q", got)
+	}
+}

shortcuts/drive/drive_export_download.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// DriveExportDownload downloads an already-generated export artifact when the
+// caller has a file token from a previous export task.
+var DriveExportDownload = common.Shortcut{
+	Service:     "drive",
+	Command:     "+export-download",
+	Description: "Download an exported file by file_token",
+	Risk:        "read",
+	Scopes: []string{
+		"docs:document:export",
+	},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file-token", Desc: "exported file token", Required: true},
+		{Name: "file-name", Desc: "preferred output filename (optional)"},
+		{Name: "output-dir", Default: ".", Desc: "local output directory (default: current directory)"},
+		{Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validate.ResourceName(runtime.Str("file-token"), "--file-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			GET("/open-apis/drive/v1/export_tasks/file/:file_token/download").
+			Set("file_token", runtime.Str("file-token")).
+			Set("output_dir", runtime.Str("output-dir"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		// Reuse the shared export download helper so overwrite checks, filename
+		// resolution, and output metadata stay consistent with drive +export.
+		out, err := downloadDriveExportFile(
+			ctx,
+			runtime,
+			runtime.Str("file-token"),
+			runtime.Str("output-dir"),
+			runtime.Str("file-name"),
+			runtime.Bool("overwrite"),
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}

shortcuts/drive/drive_export_test.go

@@ -0,0 +1,516 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"bytes"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestValidateDriveExportSpec(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		spec    driveExportSpec
+		wantErr string
+	}{
+		{
+			name: "markdown docx ok",
+			spec: driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "markdown"},
+		},
+		{
+			name:    "markdown non docx rejected",
+			spec:    driveExportSpec{Token: "doc123", DocType: "doc", FileExtension: "markdown"},
+			wantErr: "only supports --doc-type docx",
+		},
+		{
+			name:    "csv without sub id rejected",
+			spec:    driveExportSpec{Token: "sheet123", DocType: "sheet", FileExtension: "csv"},
+			wantErr: "--sub-id is required",
+		},
+		{
+			name:    "sub id on non csv rejected",
+			spec:    driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "pdf", SubID: "tbl_1"},
+			wantErr: "--sub-id is only used",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			err := validateDriveExportSpec(tt.spec)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("unexpected error: %v", err)
+				}
+				return
+			}
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("expected error containing %q, got %v", tt.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestDriveExportMarkdownWritesFile(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs/v1/content",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"content": "# hello\n",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"title": "Weekly Notes"},
+				},
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "markdown",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Join(tmpDir, "Weekly Notes.md"))
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "# hello\n" {
+		t.Fatalf("markdown content = %q", string(data))
+	}
+	if !strings.Contains(stdout.String(), "Weekly Notes.md") {
+		t.Fatalf("stdout missing file name: %s", stdout.String())
+	}
+}
+
+func TestDriveExportAsyncSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_123"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_123",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_123",
+					"file_name":      "report",
+					"file_extension": "pdf",
+					"type":           "docx",
+					"file_size":      3,
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_123/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Join(tmpDir, "report.pdf"))
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "pdf" {
+		t.Fatalf("downloaded content = %q", string(data))
+	}
+	if !strings.Contains(stdout.String(), `"ticket": "tk_123"`) {
+		t.Fatalf("stdout missing ticket: %s", stdout.String())
+	}
+}
+
+func TestDriveExportReadyDownloadFailureIncludesRecoveryHint(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_ready"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_ready",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status":     0,
+					"file_token":     "box_ready",
+					"file_name":      "report",
+					"file_extension": "pdf",
+					"type":           "docx",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_ready/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile(filepath.Join(tmpDir, "report.pdf"), []byte("old"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected download recovery error, got nil")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "already exists") {
+		t.Fatalf("message missing overwrite guidance: %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "ticket=tk_ready") {
+		t.Fatalf("hint missing ticket: %q", exitErr.Detail.Hint)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "file_token=box_ready") {
+		t.Fatalf("hint missing file token: %q", exitErr.Detail.Hint)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, `lark-cli drive +export-download --file-token "box_ready" --file-name "report.pdf"`) {
+		t.Fatalf("hint missing recovery command: %q", exitErr.Detail.Hint)
+	}
+}
+
+func TestDriveExportTimeoutReturnsFollowUpCommand(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_456"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_456",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status": 2,
+				},
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"ticket": "tk_456"`) {
+		t.Fatalf("stdout missing ticket: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"timed_out": true`) {
+		t.Fatalf("stdout missing timed_out=true: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"failed": false`) {
+		t.Fatalf("stdout missing failed=false: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"job_status": 2`) {
+		t.Fatalf("stdout missing numeric job_status: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"job_status_label": "processing"`) {
+		t.Fatalf("stdout missing processing job_status_label: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"next_command": "lark-cli drive +task_result --scenario export --ticket tk_456 --file-token docx123"`) {
+		t.Fatalf("stdout missing follow-up command: %s", stdout.String())
+	}
+	if _, err := os.Stat(filepath.Join(tmpDir, "report.pdf")); !os.IsNotExist(err) {
+		t.Fatalf("unexpected downloaded file, err=%v", err)
+	}
+}
+
+func TestDriveExportPollErrorsReturnLastErrorWithRecoveryHint(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_poll_fail"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_poll_fail",
+		Status: 500,
+		Body: map[string]interface{}{
+			"code": 999,
+			"msg":  "temporary backend failure",
+		},
+	})
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected persistent poll error, got nil")
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout should stay empty on persistent poll error: %s", stdout.String())
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "temporary backend failure") {
+		t.Fatalf("message missing last poll error: %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "ticket=tk_poll_fail") {
+		t.Fatalf("hint missing ticket: %q", exitErr.Detail.Hint)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "lark-cli drive +task_result --scenario export --ticket tk_poll_fail --file-token docx123") {
+		t.Fatalf("hint missing recovery command: %q", exitErr.Detail.Hint)
+	}
+}
+
+func TestDriveExportDownloadUsesProvidedFileName(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_789/download",
+		Status:  200,
+		RawBody: []byte("csv"),
+		Headers: http.Header{
+			"Content-Type": []string{"text/csv"},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveExportDownload, []string{
+		"+export-download",
+		"--file-token", "box_789",
+		"--file-name", "custom.csv",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Join(tmpDir, "custom.csv"))
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "csv" {
+		t.Fatalf("downloaded content = %q", string(data))
+	}
+}
+
+func TestDriveExportDownloadRejectsOverwriteWithoutFlag(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_dup/download",
+		Status:  200,
+		RawBody: []byte("new"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="dup.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile("dup.pdf", []byte("old"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	err := mountAndRunDrive(t, DriveExportDownload, []string{
+		"+export-download",
+		"--file-token", "box_dup",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected overwrite protection error, got nil")
+	}
+	if !strings.Contains(err.Error(), "already exists") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestSaveContentToOutputDirRejectsOverwriteWithoutFlag(t *testing.T) {
+
+	tmpDir := t.TempDir()
+	target := filepath.Join(tmpDir, "exists.txt")
+	if err := os.WriteFile(target, []byte("old"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("Getwd() error: %v", err)
+	}
+	if err := os.Chdir(tmpDir); err != nil {
+		t.Fatalf("Chdir() error: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+
+	_, err = saveContentToOutputDir(".", "exists.txt", []byte("new"), false)
+	if err == nil || !strings.Contains(err.Error(), "already exists") {
+		t.Fatalf("expected overwrite error, got %v", err)
+	}
+}
+
+func TestDriveTaskResultExportIncludesReadyFlags(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_export",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"job_status": 2,
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveTaskResult, []string{
+		"+task_result",
+		"--scenario", "export",
+		"--ticket", "tk_export",
+		"--file-token", "docx123",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"ready": false`)) {
+		t.Fatalf("stdout missing ready=false: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"failed": false`)) {
+		t.Fatalf("stdout missing failed=false: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"job_status_label": "processing"`)) {
+		t.Fatalf("stdout missing job_status_label: %s", stdout.String())
+	}
+}

shortcuts/drive/drive_import.go

@@ -0,0 +1,229 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// DriveImport uploads a local file, creates an import task, and polls until
+// the imported cloud document is ready or the local polling window expires.
+var DriveImport = common.Shortcut{
+	Service:     "drive",
+	Command:     "+import",
+	Description: "Import a local file to Drive as a cloud document (docx, sheet, bitable)",
+	Risk:        "write",
+	Scopes: []string{
+		"docs:document.media:upload",
+		"docs:document:import",
+	},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file", Desc: "local file path (e.g. .docx, .xlsx, .md; large files auto use multipart upload)", Required: true},
+		{Name: "type", Desc: "target document type (docx, sheet, bitable)", Required: true},
+		{Name: "folder-token", Desc: "target folder token (omit for root folder; API accepts empty mount_key as root)"},
+		{Name: "name", Desc: "imported file name (default: local file name without extension)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateDriveImportSpec(driveImportSpec{
+			FilePath:    runtime.Str("file"),
+			DocType:     strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+			Name:        runtime.Str("name"),
+		})
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec := driveImportSpec{
+			FilePath:    runtime.Str("file"),
+			DocType:     strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+			Name:        runtime.Str("name"),
+		}
+		fileSize, err := preflightDriveImportFile(&spec)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+
+		dry := common.NewDryRunAPI()
+		dry.Desc("Upload file (single-part or multipart) -> create import task -> poll status")
+
+		appendDriveImportUploadDryRun(dry, spec, fileSize)
+
+		dry.POST("/open-apis/drive/v1/import_tasks").
+			Desc("[2] Create import task").
+			Body(spec.CreateTaskBody("<file_token>"))
+
+		dry.GET("/open-apis/drive/v1/import_tasks/:ticket").
+			Desc("[3] Poll import task result").
+			Set("ticket", "<ticket>")
+
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := driveImportSpec{
+			FilePath:    runtime.Str("file"),
+			DocType:     strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+			Name:        runtime.Str("name"),
+		}
+		if _, err := preflightDriveImportFile(&spec); err != nil {
+			return err
+		}
+
+		// Step 1: Upload file as media
+		fileToken, uploadErr := uploadMediaForImport(ctx, runtime, spec.FilePath, spec.SourceFileName(), spec.DocType)
+		if uploadErr != nil {
+			return uploadErr
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Creating import task for %s as %s...\n", spec.TargetFileName(), spec.DocType)
+
+		// Step 2: Create import task
+		ticket, err := createDriveImportTask(runtime, spec, fileToken)
+		if err != nil {
+			return err
+		}
+
+		// Step 3: Poll task
+		fmt.Fprintf(runtime.IO().ErrOut, "Polling import task %s...\n", ticket)
+
+		status, ready, err := pollDriveImportTask(runtime, ticket)
+		if err != nil {
+			return err
+		}
+
+		// Some intermediate responses omit the final type, so fall back to the
+		// requested type to keep the output shape stable.
+		resultType := status.DocType
+		if resultType == "" {
+			resultType = spec.DocType
+		}
+		out := map[string]interface{}{
+			"ticket":           ticket,
+			"type":             resultType,
+			"ready":            ready,
+			"job_status":       status.JobStatus,
+			"job_status_label": status.StatusLabel(),
+		}
+		if status.Token != "" {
+			out["token"] = status.Token
+		}
+		if status.URL != "" {
+			out["url"] = status.URL
+		}
+		if status.JobErrorMsg != "" {
+			out["job_error_msg"] = status.JobErrorMsg
+		}
+		if status.Extra != nil {
+			out["extra"] = status.Extra
+		}
+		if !ready {
+			nextCommand := driveImportTaskResultCommand(ticket)
+			fmt.Fprintf(runtime.IO().ErrOut, "Import task is still in progress. Continue with: %s\n", nextCommand)
+			out["timed_out"] = true
+			out["next_command"] = nextCommand
+		}
+
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+func preflightDriveImportFile(spec *driveImportSpec) (int64, error) {
+	// Keep dry-run and execution aligned on path normalization, file existence,
+	// and format-specific size limits before planning the upload path.
+	safeFilePath, err := validate.SafeInputPath(spec.FilePath)
+	if err != nil {
+		return 0, output.ErrValidation("unsafe file path: %s", err)
+	}
+	spec.FilePath = safeFilePath
+
+	info, err := os.Stat(spec.FilePath)
+	if err != nil {
+		return 0, output.ErrValidation("cannot read file: %s", err)
+	}
+	if !info.Mode().IsRegular() {
+		return 0, output.ErrValidation("file must be a regular file: %s", spec.FilePath)
+	}
+	if err = validateDriveImportFileSize(spec.FilePath, spec.DocType, info.Size()); err != nil {
+		return 0, err
+	}
+	return info.Size(), nil
+}
+
+func appendDriveImportUploadDryRun(dry *common.DryRunAPI, spec driveImportSpec, fileSize int64) {
+	extra, err := buildImportMediaExtra(spec.FilePath, spec.DocType)
+	if err != nil {
+		extra = fmt.Sprintf(`{"obj_type":"%s","file_extension":"%s"}`, spec.DocType, spec.FileExtension())
+	}
+
+	if fileSize > maxDriveUploadFileSize {
+		dry.POST("/open-apis/drive/v1/medias/upload_prepare").
+			Desc("[1a] Initialize multipart upload").
+			Body(map[string]interface{}{
+				"file_name":   spec.SourceFileName(),
+				"parent_type": "ccm_import_open",
+				"parent_node": "",
+				"size":        "<file_size>",
+				"extra":       extra,
+			})
+		dry.POST("/open-apis/drive/v1/medias/upload_part").
+			Desc("[1b] Upload file parts (repeated)").
+			Body(map[string]interface{}{
+				"upload_id": "<upload_id>",
+				"seq":       "<chunk_index>",
+				"size":      "<chunk_size>",
+				"file":      "<chunk_binary>",
+			})
+		dry.POST("/open-apis/drive/v1/medias/upload_finish").
+			Desc("[1c] Finalize multipart upload and get file_token").
+			Body(map[string]interface{}{
+				"upload_id": "<upload_id>",
+				"block_num": "<block_num>",
+			})
+		return
+	}
+
+	dry.POST("/open-apis/drive/v1/medias/upload_all").
+		Desc("[1] Upload file to get file_token").
+		Body(map[string]interface{}{
+			"file_name":   spec.SourceFileName(),
+			"parent_type": "ccm_import_open",
+			"size":        "<file_size>",
+			"extra":       extra,
+			"file":        "@" + spec.FilePath,
+		})
+}
+
+// importTargetFileName returns the explicit import name when present, otherwise
+// derives one from the local file name.
+func importTargetFileName(filePath, explicitName string) string {
+	if explicitName != "" {
+		return explicitName
+	}
+	return importDefaultFileName(filePath)
+}
+
+// importDefaultFileName strips only the last extension so names like
+// "report.final.csv" become "report.final".
+func importDefaultFileName(filePath string) string {
+	base := filepath.Base(filePath)
+	ext := filepath.Ext(base)
+	if ext == "" {
+		return base
+	}
+	name := strings.TrimSuffix(base, ext)
+	if name == "" {
+		return base
+	}
+	return name
+}

shortcuts/drive/drive_import_common.go

@@ -0,0 +1,551 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var (
+	driveImportPollAttempts = 30
+	driveImportPollInterval = 2 * time.Second
+)
+
+const (
+	// These limits follow the current product-side import constraints per format.
+	driveImport20MBFileSizeLimit  int64 = 20 * 1024 * 1024
+	driveImport100MBFileSizeLimit int64 = 100 * 1024 * 1024
+	driveImport600MBFileSizeLimit int64 = 600 * 1024 * 1024
+	driveImport800MBFileSizeLimit int64 = 800 * 1024 * 1024
+)
+
+type driveMultipartUploadSession struct {
+	UploadID  string
+	BlockSize int
+	BlockNum  int
+}
+
+// driveImportExtToDocTypes defines which source file extensions can be imported
+// into which Drive-native document types.
+var driveImportExtToDocTypes = map[string][]string{
+	"docx":     {"docx"},
+	"doc":      {"docx"},
+	"txt":      {"docx"},
+	"md":       {"docx"},
+	"mark":     {"docx"},
+	"markdown": {"docx"},
+	"html":     {"docx"},
+	"xlsx":     {"sheet", "bitable"},
+	"xls":      {"sheet"},
+	"csv":      {"sheet", "bitable"},
+}
+
+// driveImportSpec contains the user-facing import inputs after normalization.
+type driveImportSpec struct {
+	FilePath    string
+	DocType     string
+	FolderToken string
+	Name        string
+}
+
+func (s driveImportSpec) FileExtension() string {
+	return strings.TrimPrefix(strings.ToLower(filepath.Ext(s.FilePath)), ".")
+}
+
+func (s driveImportSpec) SourceFileName() string {
+	return filepath.Base(s.FilePath)
+}
+
+func (s driveImportSpec) TargetFileName() string {
+	return importTargetFileName(s.FilePath, s.Name)
+}
+
+// CreateTaskBody builds the request body expected by /drive/v1/import_tasks.
+func (s driveImportSpec) CreateTaskBody(fileToken string) map[string]interface{} {
+	return map[string]interface{}{
+		"file_extension": s.FileExtension(),
+		"file_token":     fileToken,
+		"type":           s.DocType,
+		"file_name":      s.TargetFileName(),
+		"point": map[string]interface{}{
+			"mount_type": 1,
+			// The import API treats an empty mount_key as "use the caller's root
+			// folder", so preserve the zero value when --folder-token is omitted.
+			"mount_key": s.FolderToken,
+		},
+	}
+}
+
+// uploadMediaForImport uploads the source file to the temporary import media
+// endpoint and returns the file token consumed by import_tasks.
+func uploadMediaForImport(ctx context.Context, runtime *common.RuntimeContext, filePath, fileName, docType string) (string, error) {
+	importInfo, err := os.Stat(filePath)
+	if err != nil {
+		return "", output.ErrValidation("cannot read file: %s", err)
+	}
+
+	fileSize := importInfo.Size()
+	if err = validateDriveImportFileSize(filePath, docType, fileSize); err != nil {
+		return "", err
+	}
+	fileSizeValue, err := driveUploadSizeValue(fileSize)
+	if err != nil {
+		return "", err
+	}
+
+	extra, err := buildImportMediaExtra(filePath, docType)
+	if err != nil {
+		return "", err
+	}
+
+	if fileSize <= maxDriveUploadFileSize {
+		fmt.Fprintf(runtime.IO().ErrOut, "Uploading media for import: %s (%s)\n", fileName, common.FormatSize(fileSize))
+		return uploadMediaForImportAll(runtime, filePath, fileName, fileSizeValue, extra)
+	}
+
+	fmt.Fprintf(runtime.IO().ErrOut, "Uploading media for import via multipart upload: %s (%s)\n", fileName, common.FormatSize(fileSize))
+	return uploadMediaForImportMultipart(runtime, filePath, fileName, fileSizeValue, extra)
+}
+
+func uploadMediaForImportAll(runtime *common.RuntimeContext, filePath, fileName string, fileSize int, extra string) (string, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return "", output.ErrValidation("cannot read file: %s", err)
+	}
+	defer f.Close()
+
+	fd := larkcore.NewFormdata()
+	fd.AddField("file_name", fileName)
+	fd.AddField("parent_type", "ccm_import_open")
+	fd.AddField("size", fmt.Sprintf("%d", fileSize))
+	fd.AddField("extra", extra)
+	fd.AddFile("file", f)
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    "/open-apis/drive/v1/medias/upload_all",
+		Body:       fd,
+	}, larkcore.WithFileUpload())
+	if err != nil {
+		return "", wrapDriveUploadRequestError(err, "upload media failed")
+	}
+
+	data, err := parseDriveUploadResponse(apiResp, "upload media failed")
+	if err != nil {
+		return "", err
+	}
+	return extractDriveUploadFileToken(data, "upload media failed")
+}
+
+func uploadMediaForImportMultipart(runtime *common.RuntimeContext, filePath, fileName string, fileSize int, extra string) (string, error) {
+	session, err := prepareMediaImportUpload(runtime, fileName, fileSize, extra)
+	if err != nil {
+		fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload prepare failed: %s\n", err)
+		return "", err
+	}
+
+	totalBlocks := session.BlockNum
+	fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload initialized: %d chunks x %s\n", totalBlocks, common.FormatSize(int64(session.BlockSize)))
+
+	f, err := os.Open(filePath)
+	if err != nil {
+		return "", output.ErrValidation("cannot read file: %s", err)
+	}
+	defer f.Close()
+
+	buffer := make([]byte, session.BlockSize)
+	remaining := fileSize
+	uploadedBlocks := 0
+	for remaining > 0 {
+		chunkSize := session.BlockSize
+		if chunkSize > remaining {
+			chunkSize = remaining
+		}
+
+		n, readErr := io.ReadFull(f, buffer[:chunkSize])
+		if readErr != nil {
+			return "", output.ErrValidation("cannot read file: %s", readErr)
+		}
+
+		if err = uploadMediaImportPart(runtime, session.UploadID, uploadedBlocks, buffer[:n]); err != nil {
+			fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload part failed: %s\n", err)
+			return "", err
+		}
+
+		remaining -= n
+		uploadedBlocks++
+	}
+
+	if session.BlockNum > 0 && session.BlockNum != uploadedBlocks {
+		return "", output.Errorf(output.ExitAPI, "api_error", "upload prepare mismatch: expected %d blocks, uploaded %d", session.BlockNum, uploadedBlocks)
+	}
+
+	return finishMediaImportUpload(runtime, session.UploadID, uploadedBlocks)
+}
+
+func prepareMediaImportUpload(runtime *common.RuntimeContext, fileName string, fileSize int, extra string) (driveMultipartUploadSession, error) {
+	data, err := runtime.CallAPI("POST", "/open-apis/drive/v1/medias/upload_prepare", nil, map[string]interface{}{
+		"file_name":   fileName,
+		"parent_type": "ccm_import_open", // For media import uploads, parent_type must be ccm_import_open.
+		"size":        fileSize,
+		"extra":       extra,
+		"parent_node": "", // For media import uploads, parent_node must be an explicit empty string; unlike medias/upload_all, this field cannot be omitted.
+	})
+	if err != nil {
+		return driveMultipartUploadSession{}, err
+	}
+
+	session := driveMultipartUploadSession{
+		UploadID:  common.GetString(data, "upload_id"),
+		BlockSize: int(common.GetFloat(data, "block_size")),
+		BlockNum:  int(common.GetFloat(data, "block_num")),
+	}
+	if session.UploadID == "" {
+		return driveMultipartUploadSession{}, output.Errorf(output.ExitAPI, "api_error", "upload prepare failed: no upload_id returned")
+	}
+	if session.BlockSize <= 0 {
+		return driveMultipartUploadSession{}, output.Errorf(output.ExitAPI, "api_error", "upload prepare failed: invalid block_size returned")
+	}
+	if session.BlockNum <= 0 {
+		return driveMultipartUploadSession{}, output.Errorf(output.ExitAPI, "api_error", "upload prepare failed: invalid block_num returned")
+	}
+	return session, nil
+}
+
+func uploadMediaImportPart(runtime *common.RuntimeContext, uploadID string, seq int, chunk []byte) error {
+	fd := larkcore.NewFormdata()
+	fd.AddField("upload_id", uploadID)
+	fd.AddField("seq", seq)
+	fd.AddField("size", len(chunk))
+	fd.AddFile("file", bytes.NewReader(chunk))
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    "/open-apis/drive/v1/medias/upload_part",
+		Body:       fd,
+	}, larkcore.WithFileUpload())
+	if err != nil {
+		return wrapDriveUploadRequestError(err, "upload media part failed")
+	}
+
+	_, err = parseDriveUploadResponse(apiResp, "upload media part failed")
+	return err
+}
+
+func finishMediaImportUpload(runtime *common.RuntimeContext, uploadID string, blockNum int) (string, error) {
+	data, err := runtime.CallAPI("POST", "/open-apis/drive/v1/medias/upload_finish", nil, map[string]interface{}{
+		"upload_id": uploadID,
+		"block_num": blockNum,
+	})
+	if err != nil {
+		fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload finish failed: %s\n", err)
+		return "", err
+	}
+	return extractDriveUploadFileToken(data, "upload media finish failed")
+}
+
+func buildImportMediaExtra(filePath, docType string) (string, error) {
+	extraBytes, err := json.Marshal(map[string]string{
+		"obj_type":       docType,
+		"file_extension": strings.TrimPrefix(strings.ToLower(filepath.Ext(filePath)), "."),
+	})
+	if err != nil {
+		return "", output.Errorf(output.ExitInternal, "json_error", "build upload extra failed: %v", err)
+	}
+	return string(extraBytes), nil
+}
+
+func driveImportFileSizeLimit(filePath, docType string) (int64, bool) {
+	// Keep the limit mapping local to import flows so we do not widen behavior
+	// changes beyond drive +import.
+	switch strings.TrimPrefix(strings.ToLower(filepath.Ext(filePath)), ".") {
+	case "docx", "doc":
+		return driveImport600MBFileSizeLimit, true
+	case "txt", "md", "mark", "markdown", "html", "xls":
+		return driveImport20MBFileSizeLimit, true
+	case "xlsx":
+		return driveImport800MBFileSizeLimit, true
+	case "csv":
+		if docType == "bitable" {
+			return driveImport100MBFileSizeLimit, true
+		}
+		return driveImport20MBFileSizeLimit, true
+	default:
+		return 0, false
+	}
+}
+
+func validateDriveImportFileSize(filePath, docType string, fileSize int64) error {
+	limit, ok := driveImportFileSizeLimit(filePath, docType)
+	if !ok || fileSize <= limit {
+		return nil
+	}
+
+	ext := strings.TrimPrefix(strings.ToLower(filepath.Ext(filePath)), ".")
+	if ext == "csv" {
+		// CSV is the only source format whose limit depends on the target type.
+		return output.ErrValidation(
+			"file %s exceeds %s import limit for .csv when importing as %s",
+			common.FormatSize(fileSize),
+			common.FormatSize(limit),
+			docType,
+		)
+	}
+
+	return output.ErrValidation(
+		"file %s exceeds %s import limit for .%s",
+		common.FormatSize(fileSize),
+		common.FormatSize(limit),
+		ext,
+	)
+}
+
+func driveUploadSizeValue(fileSize int64) (int, error) {
+	maxInt := int64(^uint(0) >> 1)
+	if fileSize > maxInt {
+		return 0, output.ErrValidation("file %s is too large to upload", common.FormatSize(fileSize))
+	}
+	return int(fileSize), nil
+}
+
+func wrapDriveUploadRequestError(err error, action string) error {
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) {
+		return err
+	}
+	return output.ErrNetwork("%s: %v", action, err)
+}
+
+func parseDriveUploadResponse(apiResp *larkcore.ApiResp, action string) (map[string]interface{}, error) {
+	var result map[string]interface{}
+	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
+		return nil, output.Errorf(output.ExitAPI, "api_error", "%s: invalid response JSON: %v", action, err)
+	}
+
+	if larkCode := int(common.GetFloat(result, "code")); larkCode != 0 {
+		msg, _ := result["msg"].(string)
+		return nil, output.ErrAPI(larkCode, fmt.Sprintf("%s: [%d] %s", action, larkCode, msg), result["error"])
+	}
+
+	data, _ := result["data"].(map[string]interface{})
+	return data, nil
+}
+
+func extractDriveUploadFileToken(data map[string]interface{}, action string) (string, error) {
+	fileToken := common.GetString(data, "file_token")
+	if fileToken == "" {
+		return "", output.Errorf(output.ExitAPI, "api_error", "%s: no file_token returned", action)
+	}
+	return fileToken, nil
+}
+
+// validateDriveImportSpec enforces the CLI-level compatibility rules before any
+// upload or import request is sent to the backend.
+func validateDriveImportSpec(spec driveImportSpec) error {
+	ext := spec.FileExtension()
+	if ext == "" {
+		return output.ErrValidation("file must have an extension (e.g. .md, .docx, .xlsx)")
+	}
+
+	switch spec.DocType {
+	case "docx", "sheet", "bitable":
+	default:
+		return output.ErrValidation("unsupported target document type: %s. Supported types are: docx, sheet, bitable", spec.DocType)
+	}
+
+	supportedTypes, ok := driveImportExtToDocTypes[ext]
+	if !ok {
+		return output.ErrValidation("unsupported file extension: %s. Supported extensions are: docx, doc, txt, md, mark, markdown, html, xlsx, xls, csv", ext)
+	}
+
+	typeAllowed := false
+	// Validate the extension/type pair locally so users get a precise error
+	// before the file upload step.
+	for _, allowedType := range supportedTypes {
+		if allowedType == spec.DocType {
+			typeAllowed = true
+			break
+		}
+	}
+	if !typeAllowed {
+		var hint string
+		switch ext {
+		case "xlsx", "csv":
+			hint = fmt.Sprintf(".%s files can only be imported as 'sheet' or 'bitable', not '%s'", ext, spec.DocType)
+		case "xls":
+			hint = fmt.Sprintf(".xls files can only be imported as 'sheet', not '%s'", spec.DocType)
+		default:
+			hint = fmt.Sprintf(".%s files can only be imported as 'docx', not '%s'", ext, spec.DocType)
+		}
+		return output.ErrValidation("file type mismatch: %s", hint)
+	}
+
+	if strings.TrimSpace(spec.FolderToken) != "" {
+		if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+	}
+
+	return nil
+}
+
+// driveImportStatus captures the backend fields needed to decide whether the
+// import can be surfaced immediately or requires a follow-up poll.
+type driveImportStatus struct {
+	Ticket      string
+	DocType     string
+	Token       string
+	URL         string
+	JobErrorMsg string
+	Extra       interface{}
+	JobStatus   int
+}
+
+func (s driveImportStatus) Ready() bool {
+	return s.Token != "" && s.JobStatus == 0
+}
+
+func (s driveImportStatus) Pending() bool {
+	return s.JobStatus == 1 || s.JobStatus == 2 || (s.JobStatus == 0 && s.Token == "")
+}
+
+func (s driveImportStatus) Failed() bool {
+	return !s.Ready() && !s.Pending() && s.JobStatus != 0
+}
+
+func (s driveImportStatus) StatusLabel() string {
+	switch s.JobStatus {
+	case 0:
+		// Some responses report status=0 before the imported token is materialized.
+		// Treat that intermediate state as pending rather than completed.
+		if s.Token == "" {
+			return "pending"
+		}
+		return "success"
+	case 1:
+		return "new"
+	case 2:
+		return "processing"
+	default:
+		return fmt.Sprintf("status_%d", s.JobStatus)
+	}
+}
+
+// driveImportTaskResultCommand prints the resume command returned after bounded
+// polling times out locally.
+func driveImportTaskResultCommand(ticket string) string {
+	return fmt.Sprintf("lark-cli drive +task_result --scenario import --ticket %s", ticket)
+}
+
+// createDriveImportTask creates the server-side import task after the media
+// upload has produced a reusable file token.
+func createDriveImportTask(runtime *common.RuntimeContext, spec driveImportSpec, fileToken string) (string, error) {
+	data, err := runtime.CallAPI("POST", "/open-apis/drive/v1/import_tasks", nil, spec.CreateTaskBody(fileToken))
+	if err != nil {
+		return "", err
+	}
+
+	ticket := common.GetString(data, "ticket")
+	if ticket == "" {
+		return "", output.Errorf(output.ExitAPI, "api_error", "no ticket returned from import_tasks")
+	}
+	return ticket, nil
+}
+
+// getDriveImportStatus fetches the current state of an import task by ticket.
+func getDriveImportStatus(runtime *common.RuntimeContext, ticket string) (driveImportStatus, error) {
+	if err := validate.ResourceName(ticket, "--ticket"); err != nil {
+		return driveImportStatus{}, output.ErrValidation("%s", err)
+	}
+
+	data, err := runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/drive/v1/import_tasks/%s", validate.EncodePathSegment(ticket)),
+		nil,
+		nil,
+	)
+	if err != nil {
+		return driveImportStatus{}, err
+	}
+
+	return parseDriveImportStatus(ticket, data), nil
+}
+
+// parseDriveImportStatus accepts either the wrapped API response or an already
+// extracted result object to keep the helper easy to test.
+func parseDriveImportStatus(ticket string, data map[string]interface{}) driveImportStatus {
+	result := common.GetMap(data, "result")
+	if result == nil {
+		// Some tests and helper call sites already pass the unwrapped result body.
+		result = data
+	}
+
+	return driveImportStatus{
+		Ticket:      ticket,
+		DocType:     common.GetString(result, "type"),
+		Token:       common.GetString(result, "token"),
+		URL:         common.GetString(result, "url"),
+		JobErrorMsg: common.GetString(result, "job_error_msg"),
+		Extra:       result["extra"],
+		JobStatus:   int(common.GetFloat(result, "job_status")),
+	}
+}
+
+// pollDriveImportTask waits for the import to finish within a bounded window
+// and returns the last observed status for resume-on-timeout flows.
+func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveImportStatus, bool, error) {
+	lastStatus := driveImportStatus{Ticket: ticket}
+	var lastErr error
+	hadSuccessfulPoll := false
+	for attempt := 1; attempt <= driveImportPollAttempts; attempt++ {
+		if attempt > 1 {
+			time.Sleep(driveImportPollInterval)
+		}
+
+		status, err := getDriveImportStatus(runtime, ticket)
+		if err != nil {
+			lastErr = err
+			// Log the error but continue polling.
+			fmt.Fprintf(runtime.IO().ErrOut, "Import status attempt %d/%d failed: %v\n", attempt, driveImportPollAttempts, err)
+			continue
+		}
+		lastStatus = status
+		hadSuccessfulPoll = true
+
+		// Stop immediately on terminal states and otherwise return the last known
+		// status so the caller can expose a follow-up command on timeout.
+		if status.Ready() {
+			fmt.Fprintf(runtime.IO().ErrOut, "Import completed successfully.\n")
+			return status, true, nil
+		}
+		if status.Failed() {
+			msg := strings.TrimSpace(status.JobErrorMsg)
+			if msg == "" {
+				msg = status.StatusLabel()
+			}
+			return status, false, output.Errorf(output.ExitAPI, "api_error", "import failed with status %d: %s", status.JobStatus, msg)
+		}
+	}
+	if !hadSuccessfulPoll && lastErr != nil {
+		return lastStatus, false, lastErr
+	}
+
+	return lastStatus, false, nil
+}

shortcuts/drive/drive_import_common_test.go

@@ -0,0 +1,639 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"mime"
+	"mime/multipart"
+	"os"
+	"strings"
+	"testing"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestValidateDriveImportSpecRejectsMismatchedType(t *testing.T) {
+	t.Parallel()
+
+	err := validateDriveImportSpec(driveImportSpec{
+		FilePath: "./data.xlsx",
+		DocType:  "docx",
+	})
+	if err == nil || !strings.Contains(err.Error(), "file type mismatch") {
+		t.Fatalf("expected file type mismatch error, got %v", err)
+	}
+}
+
+func TestValidateDriveImportSpecRejectsXlsBitable(t *testing.T) {
+	t.Parallel()
+
+	err := validateDriveImportSpec(driveImportSpec{
+		FilePath: "./data.xls",
+		DocType:  "bitable",
+	})
+	if err == nil || !strings.Contains(err.Error(), ".xls files can only be imported as 'sheet'") {
+		t.Fatalf("expected xls-only-sheet validation error, got %v", err)
+	}
+}
+
+func TestValidateDriveImportFileSize(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		filePath string
+		docType  string
+		fileSize int64
+		wantText string
+	}{
+		{
+			name:     "docx exceeds 600mb limit",
+			filePath: "./report.docx",
+			docType:  "docx",
+			fileSize: driveImport600MBFileSizeLimit + 1,
+			wantText: "exceeds 600.0 MB import limit for .docx",
+		},
+		{
+			name:     "csv sheet exceeds 20mb limit",
+			filePath: "./data.csv",
+			docType:  "sheet",
+			fileSize: driveImport20MBFileSizeLimit + 1,
+			wantText: "exceeds 20.0 MB import limit for .csv when importing as sheet",
+		},
+		{
+			name:     "csv bitable exceeds 100mb limit",
+			filePath: "./data.csv",
+			docType:  "bitable",
+			fileSize: driveImport100MBFileSizeLimit + 1,
+			wantText: "exceeds 100.0 MB import limit for .csv when importing as bitable",
+		},
+		{
+			name:     "xlsx within 800mb limit",
+			filePath: "./data.xlsx",
+			docType:  "sheet",
+			fileSize: driveImport800MBFileSizeLimit,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateDriveImportFileSize(tt.filePath, tt.docType, tt.fileSize)
+			if tt.wantText == "" {
+				if err != nil {
+					t.Fatalf("expected no error, got %v", err)
+				}
+				return
+			}
+			if err == nil || !strings.Contains(err.Error(), tt.wantText) {
+				t.Fatalf("error = %v, want substring %q", err, tt.wantText)
+			}
+		})
+	}
+}
+
+func TestParseDriveImportStatus(t *testing.T) {
+	t.Parallel()
+
+	status := parseDriveImportStatus("tk_123", map[string]interface{}{
+		"result": map[string]interface{}{
+			"type":          "sheet",
+			"job_status":    0,
+			"job_error_msg": "",
+			"token":         "sheet_123",
+			"url":           "https://example.com/sheets/sheet_123",
+			"extra":         []interface{}{"2000"},
+		},
+	})
+
+	if !status.Ready() {
+		t.Fatal("expected import status to be ready")
+	}
+	if status.StatusLabel() != "success" {
+		t.Fatalf("status label = %q, want %q", status.StatusLabel(), "success")
+	}
+	if status.Token != "sheet_123" {
+		t.Fatalf("token = %q, want %q", status.Token, "sheet_123")
+	}
+}
+
+func TestDriveImportStatusPendingWithoutToken(t *testing.T) {
+	t.Parallel()
+
+	status := driveImportStatus{JobStatus: 0}
+	if status.Ready() {
+		t.Fatal("expected status without token to be not ready")
+	}
+	if !status.Pending() {
+		t.Fatal("expected status without token to be pending")
+	}
+	if got := status.StatusLabel(); got != "pending" {
+		t.Fatalf("StatusLabel() = %q, want %q", got, "pending")
+	}
+}
+
+func TestDriveImportTimeoutReturnsFollowUpCommand(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "file_123"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/import_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_import"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/import_tasks/tk_import",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"type":       "sheet",
+					"job_status": 2,
+				},
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile("data.xlsx", []byte("fake-xlsx"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	prevAttempts, prevInterval := driveImportPollAttempts, driveImportPollInterval
+	driveImportPollAttempts, driveImportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveImportPollAttempts, driveImportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveImport, []string{
+		"+import",
+		"--file", "data.xlsx",
+		"--type", "sheet",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"ready": false`)) {
+		t.Fatalf("stdout missing ready=false: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"timed_out": true`)) {
+		t.Fatalf("stdout missing timed_out=true: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"next_command": "lark-cli drive +task_result --scenario import --ticket tk_import"`)) {
+		t.Fatalf("stdout missing follow-up command: %s", stdout.String())
+	}
+}
+
+func TestDriveImportUsesMultipartUploadForLargeFile(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+
+	prepareStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": 4 * 1024 * 1024,
+				"block_num":  6,
+			},
+		},
+	}
+	reg.Register(prepareStub)
+
+	partStubs := make([]*httpmock.Stub, 0, 6)
+	for i := 0; i < 6; i++ {
+		stub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_part",
+			Body: map[string]interface{}{
+				"code": 0,
+				"msg":  "ok",
+			},
+		}
+		partStubs = append(partStubs, stub)
+		reg.Register(stub)
+	}
+
+	finishStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"file_token": "file_123",
+			},
+		},
+	}
+	reg.Register(finishStub)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/import_tasks",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ticket": "tk_import"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/import_tasks/tk_import",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": map[string]interface{}{
+					"type":       "sheet",
+					"job_status": 0,
+					"token":      "sheet_123",
+					"url":        "https://example.com/sheets/sheet_123",
+				},
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	writeSizedDriveImportFile(t, "large.xlsx", int64(maxDriveUploadFileSize)+1)
+
+	err := mountAndRunDrive(t, DriveImport, []string{
+		"+import",
+		"--file", "large.xlsx",
+		"--type", "sheet",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !bytes.Contains(stdout.Bytes(), []byte(`"token": "sheet_123"`)) {
+		t.Fatalf("stdout missing imported token: %s", stdout.String())
+	}
+
+	prepareBody := decodeCapturedJSONBody(t, prepareStub)
+	if got, _ := prepareBody["parent_type"].(string); got != "ccm_import_open" {
+		t.Fatalf("prepare parent_type = %q, want %q", got, "ccm_import_open")
+	}
+	if got, _ := prepareBody["file_name"].(string); got != "large.xlsx" {
+		t.Fatalf("prepare file_name = %q, want %q", got, "large.xlsx")
+	}
+	if got, _ := prepareBody["size"].(float64); got != float64(maxDriveUploadFileSize+1) {
+		t.Fatalf("prepare size = %v, want %d", got, maxDriveUploadFileSize+1)
+	}
+
+	firstPart := decodeCapturedMultipartBody(t, partStubs[0])
+	if got := firstPart.Fields["upload_id"]; got != "upload_123" {
+		t.Fatalf("first part upload_id = %q, want %q", got, "upload_123")
+	}
+	if got := firstPart.Fields["seq"]; got != "0" {
+		t.Fatalf("first part seq = %q, want %q", got, "0")
+	}
+	if got := firstPart.Fields["size"]; got != "4194304" {
+		t.Fatalf("first part size = %q, want %q", got, "4194304")
+	}
+	if got := len(firstPart.Files["file"]); got != 4*1024*1024 {
+		t.Fatalf("first part file size = %d, want %d", got, 4*1024*1024)
+	}
+
+	lastPart := decodeCapturedMultipartBody(t, partStubs[len(partStubs)-1])
+	if got := lastPart.Fields["seq"]; got != "5" {
+		t.Fatalf("last part seq = %q, want %q", got, "5")
+	}
+	if got := lastPart.Fields["size"]; got != "1" {
+		t.Fatalf("last part size = %q, want %q", got, "1")
+	}
+	if got := len(lastPart.Files["file"]); got != 1 {
+		t.Fatalf("last part file size = %d, want %d", got, 1)
+	}
+
+	finishBody := decodeCapturedJSONBody(t, finishStub)
+	if got, _ := finishBody["upload_id"].(string); got != "upload_123" {
+		t.Fatalf("finish upload_id = %q, want %q", got, "upload_123")
+	}
+	if got, _ := finishBody["block_num"].(float64); got != 6 {
+		t.Fatalf("finish block_num = %v, want %d", got, 6)
+	}
+}
+
+func TestDriveImportMultipartPrepareValidatesResponseFields(t *testing.T) {
+	tests := []struct {
+		name     string
+		data     map[string]interface{}
+		wantText string
+	}{
+		{
+			name: "missing upload id",
+			data: map[string]interface{}{
+				"block_size": 4 * 1024 * 1024,
+				"block_num":  6,
+			},
+			wantText: "upload prepare failed: no upload_id returned",
+		},
+		{
+			name: "missing block size",
+			data: map[string]interface{}{
+				"upload_id": "upload_123",
+				"block_num": 6,
+			},
+			wantText: "upload prepare failed: invalid block_size returned",
+		},
+		{
+			name: "missing block num",
+			data: map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": 4 * 1024 * 1024,
+			},
+			wantText: "upload prepare failed: invalid block_num returned",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+			registerDriveBotTokenStub(reg)
+			reg.Register(&httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/drive/v1/medias/upload_prepare",
+				Body: map[string]interface{}{
+					"code": 0,
+					"data": tt.data,
+				},
+			})
+
+			tmpDir := t.TempDir()
+			withDriveWorkingDir(t, tmpDir)
+			writeSizedDriveImportFile(t, "large.xlsx", int64(maxDriveUploadFileSize)+1)
+
+			err := mountAndRunDrive(t, DriveImport, []string{
+				"+import",
+				"--file", "large.xlsx",
+				"--type", "sheet",
+				"--as", "bot",
+			}, f, nil)
+			if err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantText) {
+				t.Fatalf("error = %v, want substring %q", err, tt.wantText)
+			}
+		})
+	}
+}
+
+func TestDriveImportMultipartUploadPartAPIFailure(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": 4 * 1024 * 1024,
+				"block_num":  6,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_part",
+		Body: map[string]interface{}{
+			"code": 999,
+			"msg":  "chunk rejected",
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	writeSizedDriveImportFile(t, "large.xlsx", int64(maxDriveUploadFileSize)+1)
+
+	err := mountAndRunDrive(t, DriveImport, []string{
+		"+import",
+		"--file", "large.xlsx",
+		"--type", "sheet",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "upload media part failed: [999] chunk rejected") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDriveImportMultipartFinishRequiresFileToken(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": 4 * 1024 * 1024,
+				"block_num":  6,
+			},
+		},
+	})
+	for i := 0; i < 6; i++ {
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_part",
+			Body: map[string]interface{}{
+				"code": 0,
+				"msg":  "ok",
+			},
+		})
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	writeSizedDriveImportFile(t, "large.xlsx", int64(maxDriveUploadFileSize)+1)
+
+	err := mountAndRunDrive(t, DriveImport, []string{
+		"+import",
+		"--file", "large.xlsx",
+		"--type", "sheet",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "upload media finish failed: no file_token returned") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDriveImportRejectsOversizedFileByImportLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	writeSizedDriveImportFile(t, "too-large.csv", driveImport100MBFileSizeLimit+1)
+
+	err := mountAndRunDrive(t, DriveImport, []string{
+		"+import",
+		"--file", "too-large.csv",
+		"--type", "bitable",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected size limit error, got nil")
+	}
+	if !strings.Contains(err.Error(), "exceeds 100.0 MB import limit for .csv when importing as bitable") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestParseDriveUploadResponseErrors(t *testing.T) {
+	t.Parallel()
+
+	t.Run("invalid json", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := parseDriveUploadResponse(&larkcore.ApiResp{RawBody: []byte("{")}, "upload media failed")
+		if err == nil || !strings.Contains(err.Error(), "invalid response JSON") {
+			t.Fatalf("expected invalid JSON error, got %v", err)
+		}
+	})
+
+	t.Run("api code error", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := parseDriveUploadResponse(&larkcore.ApiResp{RawBody: []byte(`{"code":999,"msg":"boom","error":{"detail":"x"}}`)}, "upload media failed")
+		if err == nil || !strings.Contains(err.Error(), "upload media failed: [999] boom") {
+			t.Fatalf("expected API error, got %v", err)
+		}
+	})
+}
+
+func TestWrapDriveUploadRequestError(t *testing.T) {
+	t.Parallel()
+
+	t.Run("preserves exit error", func(t *testing.T) {
+		t.Parallel()
+
+		original := output.ErrValidation("bad input")
+		got := wrapDriveUploadRequestError(original, "upload media failed")
+		if got != original {
+			t.Fatalf("expected same exit error pointer, got %v", got)
+		}
+	})
+
+	t.Run("wraps generic error as network", func(t *testing.T) {
+		t.Parallel()
+
+		got := wrapDriveUploadRequestError(io.EOF, "upload media failed")
+		var exitErr *output.ExitError
+		if !errors.As(got, &exitErr) {
+			t.Fatalf("expected ExitError, got %T", got)
+		}
+		if exitErr.Code != output.ExitNetwork {
+			t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitNetwork)
+		}
+		if !strings.Contains(got.Error(), "upload media failed") {
+			t.Fatalf("unexpected error: %v", got)
+		}
+	})
+}
+
+type capturedMultipartBody struct {
+	Fields map[string]string
+	Files  map[string][]byte
+}
+
+func decodeCapturedJSONBody(t *testing.T, stub *httpmock.Stub) map[string]interface{} {
+	t.Helper()
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode captured JSON body: %v", err)
+	}
+	return body
+}
+
+func writeSizedDriveImportFile(t *testing.T, name string, size int64) {
+	t.Helper()
+
+	fh, err := os.Create(name)
+	if err != nil {
+		t.Fatalf("Create(%q) error: %v", name, err)
+	}
+	if err := fh.Truncate(size); err != nil {
+		t.Fatalf("Truncate(%q) error: %v", name, err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close(%q) error: %v", name, err)
+	}
+}
+
+func decodeCapturedMultipartBody(t *testing.T, stub *httpmock.Stub) capturedMultipartBody {
+	t.Helper()
+
+	contentType := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		t.Fatalf("parse multipart content type: %v", err)
+	}
+	if mediaType != "multipart/form-data" {
+		t.Fatalf("content type = %q, want multipart/form-data", mediaType)
+	}
+
+	reader := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	body := capturedMultipartBody{
+		Fields: map[string]string{},
+		Files:  map[string][]byte{},
+	}
+	for {
+		part, err := reader.NextPart()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("read multipart part: %v", err)
+		}
+
+		data, err := io.ReadAll(part)
+		if err != nil {
+			t.Fatalf("read multipart data: %v", err)
+		}
+		if part.FileName() != "" {
+			body.Files[part.FormName()] = data
+			continue
+		}
+		body.Fields[part.FormName()] = string(data)
+	}
+	return body
+}

shortcuts/drive/drive_import_test.go

@@ -0,0 +1,363 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestImportDefaultFileName(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		filePath string
+		want     string
+	}{
+		{
+			name:     "strip xlsx extension",
+			filePath: "/tmp/base-import.xlsx",
+			want:     "base-import",
+		},
+		{
+			name:     "strip last extension only",
+			filePath: "/tmp/report.final.csv",
+			want:     "report.final",
+		},
+		{
+			name:     "keep name without extension",
+			filePath: "/tmp/README",
+			want:     "README",
+		},
+		{
+			name:     "keep hidden file name when trim would be empty",
+			filePath: "/tmp/.env",
+			want:     ".env",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := importDefaultFileName(tt.filePath); got != tt.want {
+				t.Fatalf("importDefaultFileName(%q) = %q, want %q", tt.filePath, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestImportTargetFileName(t *testing.T) {
+	t.Parallel()
+
+	if got := importTargetFileName("/tmp/base-import.xlsx", "custom-name.xlsx"); got != "custom-name.xlsx" {
+		t.Fatalf("explicit name should win, got %q", got)
+	}
+	if got := importTargetFileName("/tmp/base-import.xlsx", ""); got != "base-import" {
+		t.Fatalf("default import name = %q, want %q", got, "base-import")
+	}
+}
+
+func TestDriveImportDryRunUsesExtensionlessDefaultName(t *testing.T) {
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	if err := os.WriteFile("base-import.xlsx", []byte("fake-xlsx"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	cmd := &cobra.Command{Use: "drive +import"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "./base-import.xlsx"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "bitable"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if err := cmd.Flags().Set("folder-token", "fld_test"); err != nil {
+		t.Fatalf("set --folder-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveImport.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 3 {
+		t.Fatalf("expected 3 API calls, got %d", len(got.API))
+	}
+
+	uploadName, _ := got.API[0].Body["file_name"].(string)
+	if uploadName != "base-import.xlsx" {
+		t.Fatalf("upload file_name = %q, want %q", uploadName, "base-import.xlsx")
+	}
+
+	importName, _ := got.API[1].Body["file_name"].(string)
+	if importName != "base-import" {
+		t.Fatalf("import task file_name = %q, want %q", importName, "base-import")
+	}
+}
+
+func TestDriveImportDryRunShowsMultipartUploadForLargeFile(t *testing.T) {
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	fh, err := os.Create("large.xlsx")
+	if err != nil {
+		t.Fatalf("Create() error: %v", err)
+	}
+	if err := fh.Truncate(int64(maxDriveUploadFileSize) + 1); err != nil {
+		t.Fatalf("Truncate() error: %v", err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close() error: %v", err)
+	}
+
+	cmd := &cobra.Command{Use: "drive +import"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "./large.xlsx"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "sheet"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveImport.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Method string `json:"method"`
+			URL    string `json:"url"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 5 {
+		t.Fatalf("expected 5 API calls, got %d", len(got.API))
+	}
+	if got.API[0].URL != "/open-apis/drive/v1/medias/upload_prepare" {
+		t.Fatalf("dry-run first URL = %q, want upload_prepare", got.API[0].URL)
+	}
+	if got.API[1].URL != "/open-apis/drive/v1/medias/upload_part" {
+		t.Fatalf("dry-run second URL = %q, want upload_part", got.API[1].URL)
+	}
+	if got.API[2].URL != "/open-apis/drive/v1/medias/upload_finish" {
+		t.Fatalf("dry-run third URL = %q, want upload_finish", got.API[2].URL)
+	}
+}
+
+func TestDriveImportDryRunReturnsErrorForUnsafePath(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +import"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "../outside.md"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "docx"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := DriveImport.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API   []struct{} `json:"api"`
+		Error string     `json:"error"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if got.Error == "" || !strings.Contains(got.Error, "unsafe file path") {
+		t.Fatalf("dry-run error = %q, want unsafe file path error", got.Error)
+	}
+	if len(got.API) != 0 {
+		t.Fatalf("expected no API calls when preflight fails, got %d", len(got.API))
+	}
+}
+
+func TestDriveImportDryRunReturnsErrorForOversizedMarkdown(t *testing.T) {
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	fh, err := os.Create("large.md")
+	if err != nil {
+		t.Fatalf("Create() error: %v", err)
+	}
+	if err := fh.Truncate(driveImport20MBFileSizeLimit + 5*1024*1024); err != nil {
+		t.Fatalf("Truncate() error: %v", err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close() error: %v", err)
+	}
+
+	cmd := &cobra.Command{Use: "drive +import"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "./large.md"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "docx"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveImport.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API   []struct{} `json:"api"`
+		Error string     `json:"error"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if got.Error == "" || !strings.Contains(got.Error, "exceeds 20.0 MB import limit for .md") {
+		t.Fatalf("dry-run error = %q, want oversized markdown error", got.Error)
+	}
+	if len(got.API) != 0 {
+		t.Fatalf("expected no API calls when size preflight fails, got %d", len(got.API))
+	}
+}
+
+func TestDriveImportDryRunReturnsErrorForDirectoryInput(t *testing.T) {
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	if err := os.Mkdir("folder-input", 0755); err != nil {
+		t.Fatalf("Mkdir() error: %v", err)
+	}
+
+	cmd := &cobra.Command{Use: "drive +import"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "./folder-input"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "docx"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveImport.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API   []struct{} `json:"api"`
+		Error string     `json:"error"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if got.Error == "" || !strings.Contains(got.Error, "file must be a regular file") {
+		t.Fatalf("dry-run error = %q, want regular file error", got.Error)
+	}
+	if len(got.API) != 0 {
+		t.Fatalf("expected no API calls when file type preflight fails, got %d", len(got.API))
+	}
+}
+
+func TestDriveImportCreateTaskBodyKeepsEmptyMountKeyForRoot(t *testing.T) {
+	t.Parallel()
+
+	spec := driveImportSpec{
+		FilePath: "/tmp/README.md",
+		DocType:  "docx",
+	}
+
+	body := spec.CreateTaskBody("file_token_test")
+	point, ok := body["point"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("point = %#v, want map", body["point"])
+	}
+
+	raw, exists := point["mount_key"]
+	if !exists {
+		t.Fatal("mount_key missing; want empty string for root import")
+	}
+	got, ok := raw.(string)
+	if !ok {
+		t.Fatalf("mount_key type = %T, want string", raw)
+	}
+	if got != "" {
+		t.Fatalf("mount_key = %q, want empty string for root import", got)
+	}
+
+	spec.FolderToken = "fld_test"
+	body = spec.CreateTaskBody("file_token_test")
+	point, ok = body["point"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("point = %#v, want map", body["point"])
+	}
+	if got, _ := point["mount_key"].(string); got != "fld_test" {
+		t.Fatalf("mount_key = %q, want %q", got, "fld_test")
+	}
+}

shortcuts/drive/drive_io_test.go

@@ -5,9 +5,11 @@ package drive
 
 import (
 	"bytes"
+	"fmt"
 	"net/http"
 	"os"
 	"strings"
+	"sync/atomic"
 	"testing"
 
 	"github.com/spf13/cobra"
@@ -18,9 +20,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+var driveTestConfigSeq atomic.Int64
+
 func driveTestConfig() *core.CliConfig {
 	return &core.CliConfig{
-		AppID: "drive-test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+		AppID: fmt.Sprintf("drive-test-app-%d", driveTestConfigSeq.Add(1)), AppSecret: "test-secret", Brand: core.BrandFeishu,
 	}
 }
 

shortcuts/drive/drive_move.go

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// DriveMove moves a Drive file or folder and handles the async task polling
+// required by folder moves.
+var DriveMove = common.Shortcut{
+	Service:     "drive",
+	Command:     "+move",
+	Description: "Move a file or folder to another location in Drive",
+	Risk:        "write",
+	Scopes:      []string{"space:document:move"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file-token", Desc: "file or folder token to move", Required: true},
+		{Name: "type", Desc: "file type (file, docx, bitable, doc, sheet, mindnote, folder, slides)", Required: true},
+		{Name: "folder-token", Desc: "target folder token (default: root folder)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateDriveMoveSpec(driveMoveSpec{
+			FileToken:   runtime.Str("file-token"),
+			FileType:    strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+		})
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec := driveMoveSpec{
+			FileToken:   runtime.Str("file-token"),
+			FileType:    strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+		}
+
+		dry := common.NewDryRunAPI().
+			Desc("Move file or folder in Drive")
+
+		dry.POST("/open-apis/drive/v1/files/:file_token/move").
+			Desc("[1] Move file/folder").
+			Set("file_token", spec.FileToken).
+			Body(spec.RequestBody())
+
+		// If moving a folder, show the async task check step
+		if spec.FileType == "folder" {
+			dry.GET("/open-apis/drive/v1/files/task_check").
+				Desc("[2] Poll async task status (for folder move)").
+				Params(driveTaskCheckParams("<task_id>"))
+		}
+
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := driveMoveSpec{
+			FileToken:   runtime.Str("file-token"),
+			FileType:    strings.ToLower(runtime.Str("type")),
+			FolderToken: runtime.Str("folder-token"),
+		}
+
+		// Default to the caller's root folder so the command can move items
+		// without requiring an explicit destination in common cases.
+		if spec.FolderToken == "" {
+			fmt.Fprintf(runtime.IO().ErrOut, "No target folder specified, getting root folder...\n")
+			rootToken, err := getRootFolderToken(ctx, runtime)
+			if err != nil {
+				return err
+			}
+			if rootToken == "" {
+				return output.Errorf(output.ExitAPI, "api_error", "get root folder token failed, root folder is empty")
+			}
+			spec.FolderToken = rootToken
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Moving %s %s to folder %s...\n", spec.FileType, common.MaskToken(spec.FileToken), common.MaskToken(spec.FolderToken))
+
+		data, err := runtime.CallAPI(
+			"POST",
+			fmt.Sprintf("/open-apis/drive/v1/files/%s/move", validate.EncodePathSegment(spec.FileToken)),
+			nil,
+			spec.RequestBody(),
+		)
+		if err != nil {
+			return err
+		}
+
+		// Folder moves are asynchronous; file moves complete in the initial call.
+		if spec.FileType == "folder" {
+			taskID := common.GetString(data, "task_id")
+			if taskID == "" {
+				return output.Errorf(output.ExitAPI, "api_error", "move folder returned no task_id")
+			}
+
+			fmt.Fprintf(runtime.IO().ErrOut, "Folder move is async, polling task %s...\n", taskID)
+
+			status, ready, err := pollDriveTaskCheck(runtime, taskID)
+			if err != nil {
+				return err
+			}
+
+			// Include both the source and destination identifiers so a timed-out
+			// folder move can be resumed or inspected without reconstructing inputs.
+			out := map[string]interface{}{
+				"task_id":      taskID,
+				"status":       status.StatusLabel(),
+				"file_token":   spec.FileToken,
+				"folder_token": spec.FolderToken,
+				"ready":        ready,
+			}
+			if !ready {
+				nextCommand := driveTaskCheckResultCommand(taskID)
+				fmt.Fprintf(runtime.IO().ErrOut, "Folder move task is still in progress. Continue with: %s\n", nextCommand)
+				out["timed_out"] = true
+				out["next_command"] = nextCommand
+			}
+
+			runtime.Out(out, nil)
+		} else {
+			// Non-folder moves are synchronous, so the initial request is the final
+			// outcome and no follow-up task metadata is needed.
+			runtime.Out(map[string]interface{}{
+				"file_token":   spec.FileToken,
+				"folder_token": spec.FolderToken,
+				"type":         spec.FileType,
+			}, nil)
+		}
+
+		return nil
+	},
+}
+
+// getRootFolderToken resolves the caller's Drive root folder token so other
+// commands can safely use it as a default destination.
+func getRootFolderToken(ctx context.Context, runtime *common.RuntimeContext) (string, error) {
+	data, err := runtime.CallAPI("GET", "/open-apis/drive/explorer/v2/root_folder/meta", nil, nil)
+	if err != nil {
+		return "", err
+	}
+
+	token := common.GetString(data, "token")
+	if token == "" {
+		return "", output.Errorf(output.ExitAPI, "api_error", "root_folder/meta returned no token")
+	}
+
+	return token, nil
+}

shortcuts/drive/drive_move_common.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var (
+	driveMovePollAttempts = 30
+	driveMovePollInterval = 2 * time.Second
+)
+
+// driveMoveAllowedTypes mirrors the document kinds accepted by the Drive move
+// endpoint that this shortcut wraps.
+var driveMoveAllowedTypes = map[string]bool{
+	"file":     true,
+	"docx":     true,
+	"bitable":  true,
+	"doc":      true,
+	"sheet":    true,
+	"mindnote": true,
+	"folder":   true,
+	"slides":   true,
+}
+
+// driveMoveSpec contains the normalized input needed to issue a move request.
+type driveMoveSpec struct {
+	FileToken   string
+	FileType    string
+	FolderToken string
+}
+
+func (s driveMoveSpec) RequestBody() map[string]interface{} {
+	return map[string]interface{}{
+		"type":         s.FileType,
+		"folder_token": s.FolderToken,
+	}
+}
+
+func validateDriveMoveSpec(spec driveMoveSpec) error {
+	if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
+		return output.ErrValidation("%s", err)
+	}
+	if strings.TrimSpace(spec.FolderToken) != "" {
+		if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+	}
+	if !driveMoveAllowedTypes[spec.FileType] {
+		return output.ErrValidation("unsupported file type: %s. Supported types: file, docx, bitable, doc, sheet, mindnote, folder, slides", spec.FileType)
+	}
+	return nil
+}
+
+// driveTaskCheckStatus represents the status payload returned by
+// /drive/v1/files/task_check for async folder operations.
+type driveTaskCheckStatus struct {
+	TaskID string
+	Status string
+}
+
+func (s driveTaskCheckStatus) Ready() bool {
+	return strings.EqualFold(strings.TrimSpace(s.Status), "success")
+}
+
+func (s driveTaskCheckStatus) Failed() bool {
+	return strings.EqualFold(strings.TrimSpace(s.Status), "failed")
+}
+
+func (s driveTaskCheckStatus) Pending() bool {
+	return !s.Ready() && !s.Failed()
+}
+
+func (s driveTaskCheckStatus) StatusLabel() string {
+	status := strings.TrimSpace(s.Status)
+	if status == "" {
+		// Empty status is treated as unknown so callers can still render a
+		// meaningful label instead of an empty string.
+		return "unknown"
+	}
+	return status
+}
+
+// driveTaskCheckResultCommand prints the resume command shown when bounded
+// polling ends before the backend task completes.
+func driveTaskCheckResultCommand(taskID string) string {
+	return fmt.Sprintf("lark-cli drive +task_result --scenario task_check --task-id %s", taskID)
+}
+
+// driveTaskCheckParams keeps the task_check query parameter shape in one place
+// for both dry-run and execution paths.
+func driveTaskCheckParams(taskID string) map[string]interface{} {
+	return map[string]interface{}{"task_id": taskID}
+}
+
+// getDriveTaskCheckStatus fetches and validates the current state of an async
+// folder move or delete task.
+func getDriveTaskCheckStatus(runtime *common.RuntimeContext, taskID string) (driveTaskCheckStatus, error) {
+	if err := validate.ResourceName(taskID, "--task-id"); err != nil {
+		return driveTaskCheckStatus{}, output.ErrValidation("%s", err)
+	}
+
+	data, err := runtime.CallAPI("GET", "/open-apis/drive/v1/files/task_check", driveTaskCheckParams(taskID), nil)
+	if err != nil {
+		return driveTaskCheckStatus{}, err
+	}
+
+	return parseDriveTaskCheckStatus(taskID, data), nil
+}
+
+// parseDriveTaskCheckStatus tolerates both wrapped and already-unwrapped
+// response shapes used in tests and helpers.
+func parseDriveTaskCheckStatus(taskID string, data map[string]interface{}) driveTaskCheckStatus {
+	result := common.GetMap(data, "result")
+	if result == nil {
+		result = data
+	}
+
+	return driveTaskCheckStatus{
+		TaskID: taskID,
+		Status: common.GetString(result, "status"),
+	}
+}
+
+// pollDriveTaskCheck polls the backend for a bounded period and returns the
+// last seen status so callers can emit a follow-up command when needed.
+func pollDriveTaskCheck(runtime *common.RuntimeContext, taskID string) (driveTaskCheckStatus, bool, error) {
+	lastStatus := driveTaskCheckStatus{TaskID: taskID}
+	for attempt := 1; attempt <= driveMovePollAttempts; attempt++ {
+		if attempt > 1 {
+			time.Sleep(driveMovePollInterval)
+		}
+
+		status, err := getDriveTaskCheckStatus(runtime, taskID)
+		if err != nil {
+			fmt.Fprintf(runtime.IO().ErrOut, "Error polling task %s: %s\n", taskID, err)
+			continue
+		}
+		lastStatus = status
+		// Success and failure are terminal backend states. Any other value is kept
+		// as pending so the caller can decide whether to continue or resume later.
+		if status.Ready() {
+			fmt.Fprintf(runtime.IO().ErrOut, "Folder move completed successfully.\n")
+			return status, true, nil
+		}
+		if status.Failed() {
+			return status, false, output.Errorf(output.ExitAPI, "api_error", "folder move task failed")
+		}
+	}
+
+	return lastStatus, false, nil
+}

shortcuts/drive/drive_move_common_test.go

@@ -0,0 +1,194 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestParseDriveTaskCheckStatusFallback(t *testing.T) {
+	t.Parallel()
+
+	status := parseDriveTaskCheckStatus("task_123", map[string]interface{}{
+		"status": "success",
+	})
+
+	if !status.Ready() {
+		t.Fatal("expected task check status to be ready")
+	}
+	if status.StatusLabel() != "success" {
+		t.Fatalf("status label = %q, want %q", status.StatusLabel(), "success")
+	}
+}
+
+func TestDriveTaskCheckStatusPendingAndUnknownLabel(t *testing.T) {
+	t.Parallel()
+
+	status := driveTaskCheckStatus{}
+	if !status.Pending() {
+		t.Fatal("expected empty status to be treated as pending")
+	}
+	if got := status.StatusLabel(); got != "unknown" {
+		t.Fatalf("StatusLabel() = %q, want %q", got, "unknown")
+	}
+}
+
+func TestValidateDriveMoveSpecRejectsUnsupportedType(t *testing.T) {
+	t.Parallel()
+
+	err := validateDriveMoveSpec(driveMoveSpec{
+		FileToken: "file_token_test",
+		FileType:  "unsupported_type",
+	})
+	if err == nil {
+		t.Fatal("expected unsupported type error, got nil")
+	}
+	if got := err.Error(); !bytes.Contains([]byte(got), []byte("unsupported file type")) {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDriveMoveDryRunFolderIncludesTaskCheckParams(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +move"}
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	if err := cmd.Flags().Set("file-token", "fld_src"); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+	if err := cmd.Flags().Set("type", "folder"); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if err := cmd.Flags().Set("folder-token", "fld_dst"); err != nil {
+		t.Fatalf("set --folder-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := DriveMove.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 2 {
+		t.Fatalf("expected 2 API calls, got %d", len(got.API))
+	}
+	if got.API[1].Params["task_id"] != "<task_id>" {
+		t.Fatalf("task check params = %#v", got.API[1].Params)
+	}
+}
+
+func TestDriveMoveFolderSuccessUsesTaskCheckHelper(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/fld_src/move",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"task_id": "task_123"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/files/task_check",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"status": "success"},
+		},
+	})
+
+	prevAttempts, prevInterval := driveMovePollAttempts, driveMovePollInterval
+	driveMovePollAttempts, driveMovePollInterval = 1, 0
+	t.Cleanup(func() {
+		driveMovePollAttempts, driveMovePollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveMove, []string{
+		"+move",
+		"--file-token", "fld_src",
+		"--type", "folder",
+		"--folder-token", "fld_dst",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"task_id": "task_123"`)) {
+		t.Fatalf("stdout missing task id: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"ready": true`)) {
+		t.Fatalf("stdout missing ready=true: %s", stdout.String())
+	}
+}
+
+func TestDriveMoveFolderTimeoutReturnsFollowUpCommand(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/fld_src/move",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"task_id": "task_123"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/files/task_check",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"status": "pending"},
+		},
+	})
+
+	prevAttempts, prevInterval := driveMovePollAttempts, driveMovePollInterval
+	driveMovePollAttempts, driveMovePollInterval = 1, 0
+	t.Cleanup(func() {
+		driveMovePollAttempts, driveMovePollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveMove, []string{
+		"+move",
+		"--file-token", "fld_src",
+		"--type", "folder",
+		"--folder-token", "fld_dst",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"ready": false`)) {
+		t.Fatalf("stdout missing ready=false: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"timed_out": true`)) {
+		t.Fatalf("stdout missing timed_out=true: %s", stdout.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"next_command": "lark-cli drive +task_result --scenario task_check --task-id task_123"`)) {
+		t.Fatalf("stdout missing follow-up command: %s", stdout.String())
+	}
+}

shortcuts/drive/drive_move_test.go

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestDriveMoveUsesRootFolderWhenFolderTokenMissing(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/explorer/v2/root_folder/meta",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"token": "folder_root_token_test",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/file_token_test/move",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveMove, []string{
+		"+move",
+		"--file-token", "file_token_test",
+		"--type", "file",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"folder_token": "folder_root_token_test"`) {
+		t.Fatalf("stdout missing resolved root folder token: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"file_token": "file_token_test"`) {
+		t.Fatalf("stdout missing file token: %s", stdout.String())
+	}
+}
+
+func TestDriveMoveRootFolderLookupRequiresToken(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	registerDriveBotTokenStub(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/explorer/v2/root_folder/meta",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveMove, []string{
+		"+move",
+		"--file-token", "file_token_test",
+		"--type", "file",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected missing root folder token error, got nil")
+	}
+	if !strings.Contains(err.Error(), "root_folder/meta returned no token") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

shortcuts/drive/drive_task_result.go

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// DriveTaskResult exposes a unified read path for the async task types produced
+// by Drive import, export, and folder move flows.
+var DriveTaskResult = common.Shortcut{
+	Service:     "drive",
+	Command:     "+task_result",
+	Description: "Poll async task result for import, export, move, or delete operations",
+	Risk:        "read",
+	Scopes:      []string{"drive:drive.metadata:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "ticket", Desc: "async task ticket (for import/export tasks)", Required: false},
+		{Name: "task-id", Desc: "async task ID (for move/delete folder tasks)", Required: false},
+		{Name: "scenario", Desc: "task scenario: import, export, or task_check", Required: true},
+		{Name: "file-token", Desc: "source document token used for export task status lookup", Required: false},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		scenario := strings.ToLower(runtime.Str("scenario"))
+		validScenarios := map[string]bool{
+			"import":     true,
+			"export":     true,
+			"task_check": true,
+		}
+		if !validScenarios[scenario] {
+			return output.ErrValidation("unsupported scenario: %s. Supported scenarios: import, export, task_check", scenario)
+		}
+
+		// Validate required params based on scenario
+		switch scenario {
+		case "import", "export":
+			if runtime.Str("ticket") == "" {
+				return output.ErrValidation("--ticket is required for %s scenario", scenario)
+			}
+			if err := validate.ResourceName(runtime.Str("ticket"), "--ticket"); err != nil {
+				return output.ErrValidation("%s", err)
+			}
+		case "task_check":
+			if runtime.Str("task-id") == "" {
+				return output.ErrValidation("--task-id is required for task_check scenario")
+			}
+			if err := validate.ResourceName(runtime.Str("task-id"), "--task-id"); err != nil {
+				return output.ErrValidation("%s", err)
+			}
+		}
+
+		// For export scenario, file-token is required
+		if scenario == "export" && runtime.Str("file-token") == "" {
+			return output.ErrValidation("--file-token is required for export scenario")
+		}
+		if scenario == "export" {
+			if err := validate.ResourceName(runtime.Str("file-token"), "--file-token"); err != nil {
+				return output.ErrValidation("%s", err)
+			}
+		}
+
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		scenario := strings.ToLower(runtime.Str("scenario"))
+		ticket := runtime.Str("ticket")
+		taskID := runtime.Str("task-id")
+		fileToken := runtime.Str("file-token")
+
+		dry := common.NewDryRunAPI()
+		dry.Desc(fmt.Sprintf("Poll async task result for %s scenario", scenario))
+
+		switch scenario {
+		case "import":
+			dry.GET("/open-apis/drive/v1/import_tasks/:ticket").
+				Desc("[1] Query import task result").
+				Set("ticket", ticket)
+		case "export":
+			dry.GET("/open-apis/drive/v1/export_tasks/:ticket").
+				Desc("[1] Query export task result").
+				Set("ticket", ticket).
+				Params(map[string]interface{}{"token": fileToken})
+		case "task_check":
+			dry.GET("/open-apis/drive/v1/files/task_check").
+				Desc("[1] Query move/delete folder task status").
+				Params(driveTaskCheckParams(taskID))
+		}
+
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		scenario := strings.ToLower(runtime.Str("scenario"))
+		ticket := runtime.Str("ticket")
+		taskID := runtime.Str("task-id")
+		fileToken := runtime.Str("file-token")
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Querying %s task result...\n", scenario)
+
+		var result map[string]interface{}
+		var err error
+
+		// Each scenario maps to a different backend API, but this shortcut keeps
+		// the CLI surface uniform for resume-on-timeout workflows.
+		switch scenario {
+		case "import":
+			result, err = queryImportTask(runtime, ticket)
+		case "export":
+			result, err = queryExportTask(runtime, ticket, fileToken)
+		case "task_check":
+			result, err = queryTaskCheck(runtime, taskID)
+		}
+
+		if err != nil {
+			return err
+		}
+
+		runtime.Out(result, nil)
+		return nil
+	},
+}
+
+// queryImportTask returns a stable, shortcut-friendly view of the import task.
+func queryImportTask(runtime *common.RuntimeContext, ticket string) (map[string]interface{}, error) {
+	status, err := getDriveImportStatus(runtime, ticket)
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]interface{}{
+		"scenario":         "import",
+		"ticket":           status.Ticket,
+		"type":             status.DocType,
+		"ready":            status.Ready(),
+		"failed":           status.Failed(),
+		"job_status":       status.JobStatus,
+		"job_status_label": status.StatusLabel(),
+		"job_error_msg":    status.JobErrorMsg,
+		"token":            status.Token,
+		"url":              status.URL,
+		"extra":            status.Extra,
+	}, nil
+}
+
+// queryExportTask returns the export task status together with download metadata
+// once the backend has produced the exported file.
+func queryExportTask(runtime *common.RuntimeContext, ticket, fileToken string) (map[string]interface{}, error) {
+	status, err := getDriveExportStatus(runtime, fileToken, ticket)
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]interface{}{
+		"scenario":         "export",
+		"ticket":           status.Ticket,
+		"ready":            status.Ready(),
+		"failed":           status.Failed(),
+		"file_extension":   status.FileExtension,
+		"type":             status.DocType,
+		"file_name":        status.FileName,
+		"file_token":       status.FileToken,
+		"file_size":        status.FileSize,
+		"job_error_msg":    status.JobErrorMsg,
+		"job_status":       status.JobStatus,
+		"job_status_label": status.StatusLabel(),
+	}, nil
+}
+
+// queryTaskCheck returns the normalized status of a folder move/delete task.
+func queryTaskCheck(runtime *common.RuntimeContext, taskID string) (map[string]interface{}, error) {
+	status, err := getDriveTaskCheckStatus(runtime, taskID)
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]interface{}{
+		"scenario": "task_check",
+		"task_id":  status.TaskID,
+		"status":   status.StatusLabel(),
+		"ready":    status.Ready(),
+		"failed":   status.Failed(),
+	}, nil
+}