zeroclaw-labs/zeroclaw · error · anyhow::Error

grok_cli extra_args option `{flag}` must use `--flag=value`

Error message

grok_cli extra_args option `{flag}` must use `--flag=value` when its value starts with `-`

What it means

The grok_cli provider builds the Grok CLI argv itself and appends your extra_args before the provider-owned trailing `agent stdio` tokens. For flags it knows take one value (VALUE_TAKING_EXTRA_ARG_FLAGS: `--tools`, `--sandbox`, `--permission-mode`, `--rules`, `--effort`, etc.) it allows the two-token form `["--flag", "value"]`, but it rejects a value token that itself starts with `-` because a leading-dash value is indistinguishable from another flag and makes the argv ambiguous. Rewrite the pair as the inline form `--flag=value` so the boundary is explicit.

Source

Thrown at crates/zeroclaw-providers/src/grok_cli.rs:579

                .map_or((arg.as_str(), false), |(flag, _)| (flag, true));
            if RESERVED_EXTRA_ARG_FLAGS.contains(&flag) {
                anyhow::bail!(
                    "grok_cli extra_args must not include reserved flag `{flag}`. \
                     ACP transport, prompt, model, session, cwd, and update policy are owned by ZeroClaw."
                );
            }
            if has_inline_value || VALUELESS_EXTRA_ARG_FLAGS.contains(&flag) {
                index += 1;
                continue;
            }
            if VALUE_TAKING_EXTRA_ARG_FLAGS.contains(&flag) {
                let Some(value) = extra_args.get(index + 1) else {
                    anyhow::bail!(
                        "grok_cli extra_args option `{flag}` is missing its value and could consume the provider-owned ACP command"
                    );
                };
                if value.starts_with('-') {
                    anyhow::bail!(
                        "grok_cli extra_args option `{flag}` must use `--flag=value` when its value starts with `-`"
                    );
                }
                index += 2;
                continue;
            }
            anyhow::bail!(
                "grok_cli extra_args option `{flag}` must use `--flag=value` because its argument shape is not known"
            );
        }
        Ok(extra_args)
    }

    fn extra_args_set_any(extra_args: &[String], flags: &[&str]) -> bool {
        extra_args.iter().any(|arg| {
            let flag = arg.split('=').next().unwrap_or(arg);
            flags.contains(&flag)
        })

View on GitHub (pinned to 88bb9c8533)

Solutions

Rewrite the pair inline: replace ["--flag", "-value"] with ["--flag=-value"] in the grok_cli alias's extra_args
If the value is a path that legitimately starts with `-`, make it explicit (`./-file` or an absolute path)
Check for a typo: a stray `-value` token often means the preceding flag was misspelled and fell out of the known-flags list

Example fix

# before
[providers.models.grok_cli.local]
extra_args = ["--tools", "-web_search"]

# after
[providers.models.grok_cli.local]
extra_args = ["--tools=-web_search"]

Defensive patterns

Strategy: validation

Validate before calling

fn grok_extra_args_ok(args: &[String]) -> Result<(), String> {
    const VALUE_TAKING: &[&str] = &["--agent","--agents","--allow","--allowedTools","--best-of-n","--deny","--disallowed-tools","--disallowedTools","--effort","--max-turns","--permission-mode","--reasoning-effort","--rules","--sandbox","--tools"];
    let mut i = 0;
    while i < args.len() {
        if args[i].contains('=') { i += 1; continue; }
        if VALUE_TAKING.contains(&args[i].as_str()) {
            match args.get(i + 1) {
                None => return Err(format!("{}: missing value", args[i])),
                Some(v) if v.starts_with('-') =>
                    return Err(format!("use inline form `{}={}`", args[i], v)),
                _ => i += 2,
            }
        } else { i += 1; }
    }
    Ok(())
}

Try / catch

match GrokCliModelProvider::builder(alias).extra_args(args).build_to_provider() {
    Ok(p) => p,
    Err(e) if e.to_string().contains("must use `--flag=value`") => {
        // config bug: rewrite the flagged pair inline and reload config
        return ConfigFix::queue("grok_cli extra_args", e);
    }
    Err(e) => return Err(e),
}

Prevention

Author every grok_cli extra_args entry in inline `--flag=value` form
Never paste a raw shell grok command into extra_args; translate flags first
Avoid values that begin with `-` (use ./-file or absolute paths)
Run a config lint at deploy time that applies the pair-shape check above

When it happens

Trigger: Provider construction validates extra_args in normalize_and_validate_extra_args: a two-token pair whose second token starts with `-`, e.g. extra_args = ["--tools", "-web_search"] or ["--permission-mode", "-bypass"]. Fires before any CLI process is spawned.

Common situations: Forwarding deny-list entries or names that start with `-` (e.g. `--deny -read_only`); copying a working shell invocation (`grok --rules -foo`) into the alias's extra_args verbatim; negative numbers as values.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/d662a95e2aee0d37. Report an issue: GitHub.