[BUG] --max-turns CLI option is undocumented in --help and official documentation

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The --max-turns CLI option exists and functions correctly, but is completely absent
from claude --help output and inadequately documented elsewhere. Users cannot discover
this option through standard CLI help mechanisms.

This is a critical option for non-interactive (-p/--print) usage as it prevents runaway
processes and controls API costs in automated workflows, CI/CD pipelines, and scripts.

What Should Happen?

What Should Happen?

The --max-turns option should be listed in claude --help output alongside other
print-mode options like --max-budget-usd, --output-format, and --allowedTools.

Suggested help text:

--max-turns <number>    Limit the number of agentic turns in non-interactive mode (onl>

Error Messages/Logs

$ claude --help | grep -i "max-turns"
(no output - option not listed)

$ claude -p --max-turns 1 "hello"
Error: Reached max turns (1)


The option works but cannot be discovered via --help.

Steps to Reproduce

1. Run claude --help
2. Search the output for "max-turns" — it is not present
3. Run claude -p --max-turns 1 "test" — the option works correctly
4. Note the inconsistency: the option functions but is undiscoverable

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No, I don't think so (documentation was likely never added)

Claude Code Version

N/A - this appears to have never been documented in --help

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

Evidence of the option's existence

The --max-turns option is referenced in:

• The CLI reference (brief mention)
• The claude-code-action GitHub Action documentation
• Multiple third-party cheatsheets and guides

Why this matters

1. Critical for automation — The -p/--print mode is designed for scripting and

CI/CD. Without --max-turns, automated processes can run indefinitely.

1. Cost control — Undocumented rate limiting means users may incur unexpected API

costs.

1. Inconsistency — Similar options (--max-budget-usd) ARE documented in --help. The

omission of --max-turns appears to be an oversight.

1. Discoverability — Users relying on standard CLI conventions (--help) cannot find

this option.

Suggested fix

Add --max-turns <number> to the help output with documentation including:

• Default behavior (unlimited when not specified)
• That it only works with --print mode
• Recommended values for common use cases