What causes "%s: --%s requires a key and value" in charmbracelet/crush?

Supply both a key and a value as two separate arguments: `--env FOO bar`.

%s: --%s requires a key and value

Error message

%s: --%s requires a key and value

What it means

This error is thrown by parseFlagValue in internal/shellconfig/flags.go when a flag declared with kind flagKeyValue (which consumes exactly two arguments, KEY VALUE, e.g. --env NAME VALUE) does not have both arguments available. The bounds check `i+2 >= len(args)` fails, meaning only the flag itself, or the flag plus a key but no value, was supplied on the command line. applyFlags surfaces it as a usage error naming the invoking builtin command.

Source

Thrown at internal/shellconfig/flags.go:151

		if err != nil {
			return nil, 0, fmt.Errorf("%s: --%s expects an integer, got %q", args[0], name, v)
		}
		return n, i + 2, nil

	case flagFloat:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err
		}
		f, err := strconv.ParseFloat(v, 64)
		if err != nil {
			return nil, 0, fmt.Errorf("%s: --%s expects a number, got %q", args[0], name, v)
		}
		return f, i + 2, nil

	case flagKeyValue:
		if i+2 >= len(args) {
			return nil, 0, fmt.Errorf("%s: --%s requires a key and value", args[0], name)
		}
		return [2]string{args[i+1], args[i+2]}, i + 3, nil

	case flagJSONObject:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err
		}
		var object map[string]any
		if err := json.Unmarshal([]byte(v), &object); err != nil || object == nil {
			return nil, 0, fmt.Errorf("%s: --%s expects a JSON object, got %q", args[0], name, v)
		}
		return object, i + 2, nil

	case flagJSONAny:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err

View on GitHub (pinned to 7944b8e522)

Solutions

Supply both a key and a value as two separate arguments: `--env FOO bar`.
Check that any shell variables used for the value are non-empty (`echo "$BAR"`) and quote them.
Do not use `=` syntax for key/value flags; pass key and value as separate tokens.
Run the builtin's help/usage to confirm which flags require KEY VALUE pairs.

Example fix

// before
crushrc provider add anthropic --env ANTHROPIC_API_KEY
// after
crushrc provider add anthropic --env ANTHROPIC_API_KEY sk-ant-...

Defensive patterns

Strategy: validation

Validate before calling

# POSIX shell guard before invoking a key/value flag
[ $# -ge 2 ] || { echo "--env requires KEY and VALUE" >&2; exit 2; }
# verify expansion non-empty
: "${VALUE:?--env value is empty}"

Type guard

func hasKeyValueArgs(args []string, i int) bool { return i+2 < len(args) }

Try / catch

if err := applyFlags(specs, args, start, target, cmd, stderr); err != nil {
    if strings.Contains(err.Error(), "requires a key and value") {
        fmt.Fprintln(stderr, "Usage: --env KEY VALUE (two separate arguments)")
    }
    return err
}

Prevention

Always pass key and value as two separate tokens, never KEY=VALUE.
Quote variable expansions and use ${VAR:?} to fail fast on empty values.
Count trailing arguments in wrapper scripts before dispatching to the builtin.
Read the builtin's usage text to confirm which flags are KEY VALUE pairs.

When it happens

Trigger: Running a shell-config builtin (via applyFlags) with a flagKeyValue flag like --env given only the flag name (`--env` alone), or with a key but no value (`--env FOO`), or with the value accidentally consumed by shell quoting/expansion so only one trailing arg remains.

Common situations: Typing `provider add ... --env API_KEY` and forgetting the secret value; a shell variable like `--env FOO $BAR` expanding to empty so $BAR disappears; pasting an example and dropping the second token; using `=` syntax (`--env FOO=bar`) which this parser does not support, leaving only one arg.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/9703853e6a0dc183. Report an issue: GitHub.