`--mode replace_all` is named like "replace entire document" but actually replaces all matches of a selector

[Maples7]

--mode replace_all is named like "replace entire document" but actually replaces all matches of a selector

Summary

lark-cli docs +update --mode replace_all reads like "replace the whole document". The actual semantics are "replace all occurrences of a --selection-* match, anywhere in the document". The mode that does in fact replace the whole document is overwrite.

The current naming traps almost every first-time user (and especially every AI agent) into picking replace_all for a full-document rewrite, then either:

• hitting a confusing validation error because --selection-with-ellipsis / --selection-by-title is missing, or
• if a selector is supplied, having replace_all execute against an unrelated pattern.

This is compounded by #184, which is still open and reports that replace_all against documents containing protected tokens (sheet/image/mention) duplicates the entire document body — meaning a user who reaches for replace_all expecting "overwrite" semantics has a non-trivial chance of corrupting a wiki page. The naming is essentially a footgun.

Repro

A user / agent wanting to overwrite a wiki page tries:

cat new-content.md | lark-cli docs +update \
  --doc "https://my.feishu.cn/wiki/<token>" \
  --mode replace_all \
  --markdown -

Returns a validation error:

--mode replace_all requires --selection-with-ellipsis or --selection-by-title

The user must discover that the correct mode for full-document rewrite is --mode overwrite. There is currently no error hint pointing at overwrite.

Proposal

Two complementary changes:

1. Rename replace_all → replace_matches (or replace_each / replace_occurrences). Keep replace_all as a deprecated alias for one release with a [deprecated] use replace_matches instead warning. The new name makes it obvious the mode iterates over selector matches and does not act on the whole document.

2. Improve the validation error so it suggests --mode overwrite for users who likely intended a full rewrite:

   --mode replace_matches requires --selection-with-ellipsis or --selection-by-title.
   If you intended to replace the entire document body, use --mode overwrite instead.
   

Either change alone would help. Both together would close the trap.

Environment

• lark-cli 1.0.27
• macOS, Node.js, user mode

Related

• #184 — replace_all duplicates documents with protected tokens (compounds the naming hazard).
• #93 — --selection-by-title matching, now closed.

[fangshuyu-768]

Thanks for the report. We reviewed this issue again against the current implementation.

This naming/UX problem is specific to the v1 docs +update path. In v1, --mode replace_all means “replace all selector matches”, while the mode for replacing the entire document body is --mode overwrite. So the confusion described here is real for v1.

For the v2 docs update path, this specific problem does not apply. v2 uses --command (for example overwrite, append, str_replace, block_replace, etc.) rather than the old --mode replace_all surface, so the same naming trap is not present there.

Also, to set expectations clearly: the v1 docs path is no longer being actively iterated on and will be phased out in a future release. We recommend moving to the v2 docs surface (--api-version v2) for update workflows going forward.

One part of this issue has already been partially addressed on the v1 side: the validation message for replace_all now points users to --mode overwrite when they appear to be trying to replace the full document. But we do not plan to evolve the v1 command model further. The recommended path is to migrate affected workflows to v2.