Repository navigation
cli: v2 drops top-level --agent flag (v1 launch form fails with bare ShowHelp) #57778
Description
Summary
The v1 headless launch form opencode --agent <name> --prompt "<text>" (flags on the top-level command) no longer works on v2: the top-level parser has no --agent, so the command exits with a ShowHelp error about 3 ms after cli starting and no session is created. The v2 migration guide's "Breaking changes" section declares only three intentional breaking changes (plugins, server API, terminal-client config) — CLI flags are not among them, so by the guide's own rule this should be treated as a compatibility bug.
Environment
- opencode version: 2.1.2 (npm global,
@opencode/cli, channel=latest) - OS: Windows_NT 10.0.26200 (win32 x64)
- Terminal: Unavailable — fired headless from Windows Task Scheduler; terminal env vars not set
- Shell: C:\Windows\system32\cmd.exe (the scheduled task action is a PowerShell wrapper)
- Install/channel: npm; v1 → v2 npm upgrade on 2026-10-16
- Active plugins: @bybrawe/opencode-goal@1.3.49, @bybrawe/opencode-loop@0.6.8, superpowers (git), plus local plugin files under
~/.config/opencode/plugin/. Not causal here: the failure occurs at top-level argument parsing, before plugins load (a session starts fine viamini).
Reproduction
- On v2.1.2, run the v1 form:
opencode --agent em --prompt "hello" - No session starts. opencode prints help/usage and exits with an error (
CliError/ShowHelp: Help requestedin the log). - The same flags still work on the subcommand:
opencode mini --agent em --prompt "hello"—--agent stringremains documented on bothopencode runandopencode mini.
Expected Behavior
--agent should be accepted at the top level again (v1 behavior), or its removal should be declared in the migration guide's breaking changes. Impact amplifier for headless users: scheduled wrappers that launch the process detached exit 0 regardless of this CLI failure, so daily automation silently "succeeds" while nothing actually runs — in our case scheduled sessions failed silently for days after the npm upgrade.
Actual Behavior
Top-level --help FLAGS on 2.1.2 list --standalone, --server, --auto, --continue/-c, --session/-s, --prompt — no --agent. Log pair from a real failing run (~/.local/share/opencode/log/opencode.log; prompt text redacted):
timestamp=2026-10-21T11:48:59.660Z level=INFO run=65ded116 message="cli starting" version=2.1.2 channel=latest local=false args="[\"--agent\",\"em\",\"--prompt\",\"<redacted>\"]" role=cli
timestamp=2026-10-21T11:48:59.663Z level=ERROR run=65ded116 message="cli process failed" cause="Cause([Fail(~effect/cli/CliError/ShowHelp: Help requested)])" args="[\"--agent\",\"em\",\"--prompt\",\"<redacted>\"]" role=cli
Additional Context
- Consistently reproducible on 2.1.2 (win32). The same top-level form launched scheduled sessions successfully on v1 as recently as 2026-10-14.
- Diagnostic confusion:
--agent stringis still documented on therunandminisubcommand--help, and the top-level failure surfaces only as a generic ShowHelp — no "unknown flag: --agent" message naming the actual problem. - Current workaround: our wrappers now call
opencode mini --agent ... --prompt ..., which works. - For the (declared) plugins break, the V1 plugin migration guide is at https://opencode.ai/v2/docs/build/plugins/migrate-v1
Activity
opencode-agent commentedon Oct 21, 2026
Thanks for the detailed report and the log lines! I think this is a duplicate of #56842, which reports the same problem: on v2 the root
opencodecommand doesn't accept--agent, though v1 did, whileopencode mini --agent …andopencode run --agent …still do. In the code, the root command defines only--standalone,--server,--auto,-c,-sand--prompt, so the flag never reaches the TUI.Possible duplicates and related issues, ordered by likelihood:
opencode --agent <name>is rejected on the root command but works onmini/run. It's open and tracks the--agentfix.opencode -m provider/modelno longer accepted on root command (worked in v1) #56218: the same regression for-m/--modelon the root command (fix in progress in fix(cli): pass --model through to the TUI entry #48163).--modelreport, closed as a duplicate of v2:opencode -m provider/modelno longer accepted on root command (worked in v1) #56218.Your notes on the headless scheduled case would help on #56842: the vague ShowHelp failure, and the detached wrapper exiting 0 so automation fails silently. Please add them there. Until it's fixed,
opencode mini --agent … --prompt …(which you already use) oropencode run --agent … "<message>"both work.The bot will close this issue as a duplicate in 1 day unless you reply explaining how your problem is different.