chore(cli): fix examples that pipe stdin alongside a droid exec prompt

[lukealvoeiro]

Gap

droid exec ignores piped stdin when a prompt argument is also given, but two docs examples (EN and JP) pipe content and pass a prompt at the same time. Users who copy them get a run that never sees the piped content, and nothing tells them.

Evidence

Docs:

• docs/reference/cli-reference.mdx:101 (JP docs/jp/reference/cli-reference.mdx:33): example git diff | droid exec "draft release notes".
• docs/guides/droid-exec/github-actions.mdx:50-51 (JP same file, same lines): # Review and fix issues (pipe diff to stdin) followed by cat pr_changes.diff | droid exec --auto low "Review this PR diff and: ...".

Code (Factory-AI/factory-mono, apps/cli/src/entrypoints/exec/handler.ts, resolvePromptArg): the documented priority is --file > piped stdin > prompt argument, but stdin is only read when there is no prompt argument:

// 2. Automatic stdin detection (piped or redirected)
if (!promptArg && isStdinPiped()) {

Command run against a source build of the CLI on current dev, with the repo's mock LLM server:

$ droid exec -o stream-json 'arg prompt' < p.txt

Exit code 0. The only user message sent to the model was "text":"arg prompt"; the content of p.txt was never sent.

Why it matters

The GitHub Actions guide is a copy-paste CI workflow. With the current example, Droid reviews and edits code without ever seeing the PR diff, and the step still succeeds.

Fix

• CLI reference (EN + JP): describe the row as using piped content as the prompt, note that stdin is ignored when a prompt argument is also given, and use an example that only pipes (cat review-prompt.md | droid exec).
• GitHub Actions guide (EN + JP): point the prompt at the pr_changes.diff file the step already writes instead of piping it, and explain why in the comment.

Changing the CLI to merge stdin with a prompt argument would need to read stdin in cases it does not read today, which can block callers that leave a stdin pipe open (for example Node spawn with default stdio). That is a product decision, so this PR fixes the docs to match current behavior.

Validation

• Re-ran the behavior above on a source build of current dev (a227be78f53).
• Checked every other | droid exec example in docs/ (EN and JP); none of them also passes a prompt argument.

Found by the scheduled CLI arguments audit.

[factory-droid]

Droid finished @lukealvoeiro's task —— View job

---

The documentation examples now match the CLI's stdin behavior. No actionable issues were identified.

0 inline comments posted