[DOCS] CLI Reference: Ambiguity in System Prompt Flag and Mode Compatibility

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/cli-reference#system-prompt-flags

Section/Topic

The explanation of how replacement flags (--system-prompt, --system-prompt-file) interact with append flags (--append-system-prompt, --append-system-prompt-file).

Current Documentation

The documentation states: "--system-prompt and --system-prompt-file are mutually exclusive. The append flags can be used together with either replacement flag."

The accompanying table lists the following modes:

• --system-prompt: Interactive + Print
• --append-system-prompt-file: Print only

What's Wrong or Missing?

The statement "The append flags can be used together with either replacement flag" is confusing when compared to the mode restrictions in the table.

Specifically, since --append-system-prompt-file is labeled as "Print only," a user in an "Interactive" session using --system-prompt (which is "Interactive + Print") would be led to believe they can use the file-based append flag, even though the table suggests it is unavailable in that mode. This makes the "can be used together" instruction partially inaccurate for standard interactive users.

Suggested Improvement

Clarify the text to explicitly mention that combining flags is subject to the mode support of each individual flag.

Suggested Text:
"Append flags can be used together with either replacement flag, provided that the chosen mode (Interactive vs. Print) supports both flags as indicated in the table below."

Impact

High - Prevents users from using a feature

Additional Context

In the CLI reference table at https://code.claude.com/docs/en/cli-reference, the flag --append-system-prompt-file is explicitly restricted to "Print only," which creates the contradiction with the generalized "can be used together" statement for interactive users. Clearer phrasing would prevent users from attempting to use file-based appends in the interactive REPL.