docs/install: npm install succeeds with ignore-scripts=true but lark-cli is unusable

[luojiyin1987]

Summary

npm install -g @larksuite/cli can complete successfully but produce an unusable installation when npm config set ignore-scripts true is enabled.

The current README only says:

npm install -g @larksuite/cli

but does not explain that the npm package depends on postinstall to download the actual prebuilt Go binary.

This is surprising for users who intentionally keep ignore-scripts=true for security reasons.

Environment

• OS: Linux x86_64 (WSL2)
• Node.js: v22.17.1
• npm: 10.9.2
• lark-cli npm package: @larksuite/cli@1.0.5
• npm config: ignore-scripts=true

Reproduction

1. Enable script blocking:

npm config set ignore-scripts true

2. Install the CLI:

npm install -g @larksuite/cli

3. Verify the global entry exists:

type lark-cli

Example:

lark-cli is /home/luo/.nvm/versions/node/v22.17.1/bin/lark-cli

4. Run the command:

lark-cli --help

Actual Behavior

• The npm install finishes successfully.
• The global lark-cli entry exists.
• But the command exits without a useful error because the real binary was never downloaded.

In my case, the global shim points to:

~/.nvm/versions/node/v22.17.1/lib/node_modules/@larksuite/cli/scripts/run.js

and scripts/run.js expects:

../bin/lark-cli

but that file does not exist, because postinstall was skipped.

Expected Behavior

At minimum, one of the following should happen:

1. The README clearly states that the npm installation depends on postinstall, and that ignore-scripts=true will produce an incomplete installation.
2. scripts/run.js detects missing bin/lark-cli and prints an actionable error such as:
   • the binary is missing
   • postinstall may have been skipped
   • how to recover (node scripts/install.js or reinstall with scripts enabled)
3. Preferably, the package distribution should support users who block install scripts by default, for example via platform packages / optionalDependencies / bundled binaries.

Why This Matters

Many developers set ignore-scripts=true intentionally as a security baseline.

For this package, the install appears successful even though the CLI is unusable. That makes the failure mode confusing:

• README says the package is ready after npm install -g @larksuite/cli
• npm does not report an error
• the command exists in PATH
• but the CLI does not actually work

Additional Context

From the repository:

• package.json defines:
  • "bin": { "lark-cli": "scripts/run.js" }
  • "postinstall": "node scripts/install.js"
• scripts/install.js downloads the prebuilt binary from GitHub Releases / mirror
• scripts/run.js executes the downloaded binary from bin/lark-cli

So the project already has prebuilt binaries, but the npm package currently relies on postinstall to materialize them.

Suggested Improvements

1. Update both README.md and README.zh.md installation sections to document the postinstall dependency explicitly.
2. Add a friendly runtime check in scripts/run.js when bin/lark-cli is missing.
3. Consider an installation mode that does not depend on postinstall for security-conscious environments.

[liangshuo-1]

Thanks for the detailed write-up @luojiyin1987!

You're absolutely right — the silent failure when ignore-scripts=true is a poor experience. We plan to add a runtime check in run.js to detect the missing binary and print a clear error message with recovery steps.

For the platform-specific optionalDependencies approach (like esbuild/turbo do), we'll evaluate it as a longer-term improvement.

Thanks again for the suggestions!

[sang-neo03]

@luojiyin1987 Thank you for the feedback, we have optimized it in PR.