#5094: Fix browser set headers CLI option collision
cli
Cluster:
Cross-Platform Fixes
## Fix browser set headers CLI option collision
### Background
The `browser set headers` command previously the `--json` option to accept
header input. However, the parent `browser` command already defines the `--json` flag for controlling output format.
This option name collision resulted in ambiguous parsing behavior across different invocation environments, causing the headers input to be misinterpreted or ignored.
---
### Changes
This PR addresses the issue by:
- **Disambiguating CLI options**
- Rename the headers input option from `--json` to `--headers-json` with a more specific naming
- Clearly separate header input semantics from the parent output formatting flag
- **Clarifying CLI usage**
- Update command usage to reflect the new option name and expected input value type as a JSON string
---
### Example Usage
```bash
openclaw browser set headers --headers-json '{"User-Agent":"my-agent"}'
```
---
### Follow-up
The official documentation needs to update seprately to reflect this naming change. And this is **important**.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates the `browser set headers` subcommand to avoid a flag-name collision with the parent `browser --json` output flag by renaming the header-input option from `--json` to `--headers-json` in `src/cli/browser-cli-state.ts`.
However, the implementation currently still reads the payload from `opts.json`, so the renamed flag will not be honored and the command is likely broken until it reads `opts.headersJson` (commander camel-cases option names).
<h3>Confidence Score: 2/5</h3>
- This PR is not safe to merge as-is because the renamed CLI flag is not actually wired up in the handler.
- Although the intent (avoid `--json` collision) is correct, the handler still parses `opts.json` instead of the new commander option property, so the primary functionality likely breaks at runtime for users of `--headers-json`.
- src/cli/browser-cli-state.ts
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#21008: fix: Rename --url to --cookie-url in browser cookies set
by chilu18 · 2026-02-19
75.7%
#21000: fix: resolve option collision between browser and cookies set commands
by MisterGuy420 · 2026-02-19
71.6%
#6751: docs(browser): update JSON configuration format in documentation
by saltapp · 2026-02-02
69.0%
#17770: refactor(cli): reuse shared option builders
by iyoda · 2026-02-16
68.9%
#14944: fix(browser): prefer openclaw profile in headless/noSandbox environ...
by BenediktSchackenberg · 2026-02-12
68.2%
#6193: fix(browser): default to openclaw profile instead of chrome extensi...
by mikezaoldyeck · 2026-02-01
67.8%
#3783: Fix/3038 cli name moltbot
by Shuimo03 · 2026-01-29
67.1%
#18907: Fix: Improve browser error messages to avoid misleading agents
by jriff · 2026-02-17
66.5%
#4784: fix(imessage): handle non-JSON output from imsg CLI gracefully
by spiceoogway · 2026-01-30
66.0%
#11159: fix(cli): parse --profile flag after subcommand name
by hclsys · 2026-02-07
65.9%