Document Windows argument truncation when a value contains newlines

[akshat009]

On Windows, wp is a .bat wrapper and cmd.exe terminates the command at a newline, including inside a quoted argument. Any flags positioned after a multi-line value are silently dropped — the command still succeeds with whatever it received, so there is no error to search for.

Reported in wp-cli/wp-cli#2712 (2016, closed as state:unconfirmed). The STDIN workaround was posted in a comment on that thread in 2023 but isn't documented in the handbook.

Placed next to the existing Windows/UTF-8 entry, since both are argument encoding issues with a similar STDIN-style workaround.

Reproduced on WP-CLI 2.12.0 / PHP 8.2.29 / Windows 11.

Summary by CodeRabbit

• Documentation
  • Added guidance for handling Windows command-line arguments containing newlines.
  • Documented .bat wrapper limitations and recommended using STDIN or file paths with post creation and update commands.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 735737df-8d5d-4a22-825d-9a90fc8eaeee

📥 Commits

Reviewing files that changed from the base of the PR and between acf7ad2 and 912f434.

📒 Files selected for processing (1)

• guides/common-issues.md

---

📝 Walkthrough

Walkthrough

The common issues guide now documents Windows newline truncation in quoted arguments. It notes silent loss of later flags and gives STDIN and file-path workarounds for wp post create and wp post update.

Changes

Windows argument handling

Layer / File(s)	Summary
Document newline argument handling guides/common-issues.md	Documents .bat wrapper truncation, silent defaulting behavior, STDIN usage in Command Prompt and PowerShell, file-path support, and issue #2712.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documented Windows argument truncation issue caused by newline-containing values.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@guides/common-issues.md`:
- Around line 199-207: Convert each indented command example in the
documentation section to a fenced code block, using console for the shell
commands and powershell for the PowerShell example, while preserving the
commands and surrounding explanation.
- Around line 197-199: Update the example’s description of missing flag values
to say that WordPress uses the site’s default category and the current user,
replacing the installation-specific “Uncategorized” and “default user” wording
while preserving the surrounding explanation.
- Around line 201-203: Update the Windows command-line example in the documented
STDIN usage to replace the Unix-only cat command with cmd.exe’s built-in type
command, while preserving the existing wp post create arguments and piped-input
behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 336efa17-3fb2-4b43-bd65-b15c69927f20

📥 Commits

Reviewing files that changed from the base of the PR and between 5e521dc and 2a6755d.

📒 Files selected for processing (1)

• guides/common-issues.md

[Copilot]

Pull request overview

Adds handbook documentation for a Windows-specific WP-CLI limitation where multi-line argument values (containing newlines) can cause subsequent flags to be dropped due to cmd.exe/.bat parsing behavior, and documents STDIN/file-path workarounds alongside existing Windows argument-encoding guidance.

Changes:

• Documented newline-containing argument truncation behavior on Windows for wp (.bat) invocations.
• Added recommended workaround examples using STDIN in both cmd.exe and PowerShell.
• Noted that wp post create / wp post update accept - (STDIN) and file paths as alternatives.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

guides/common-issues.md:206

• The PowerShell example uses $content without showing how it’s defined, and it’s ambiguous whether $content is a prompt or a variable. Consider mirroring the CMD example by reading from a file via Get-Content, which also makes it clear how to pass multiline content over STDIN.

The same applies in PowerShell:

    $content | wp post create - --post_status=publish --post_category=3 --post_author=2