What causes "%s: --%s expects true/false, got %q" in charmbracelet/crush?

Replace the value with a literal true or false.

%s: --%s expects true/false, got %q

Error message

%s: --%s expects true/false, got %q

What it means

parseFlagValue in internal/shellconfig/flags.go validates boolean flag values with parseBool. When a --flag declared as flagBool is followed by a value that is not true/false, the error "<cmd>: --<flag> expects true/false, got %q" is returned during applyFlags while building the config. Config loading aborts at this point.

Source

Thrown at internal/shellconfig/flags.go:123

	switch spec.kind {
	case flagString:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err
		}
		return v, i + 2, nil

	case flagBoolTrue:
		return true, i + 1, nil

	case flagBool:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err
		}
		b, err := parseBool(v)
		if err != nil {
			return nil, 0, fmt.Errorf("%s: --%s expects true/false, got %q", args[0], name, v)
		}
		return b, i + 2, nil

	case flagInt:
		v, err := nextArg(args, i, name)
		if err != nil {
			return nil, 0, err
		}
		n, err := strconv.ParseInt(v, 10, 64)
		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

View on GitHub (pinned to 7944b8e522)

Solutions

Replace the value with a literal true or false.
Check the flag's declared type in the builtin's flag spec; integer/number flags use different messages.
Verify the value isn't an empty string caused by shell quoting (`--flag ""`).
If broader value acceptance is needed, extend parseBool or declare the flag with a different type.

Example fix

// before (crushrc)
options --debug yes
// after
options --debug true

Defensive patterns

Strategy: validation

Validate before calling

func isBoolLiteral(v string) bool {
	_, err := strconv.ParseBool(v)
	return err == nil
}

Try / catch

err := cfg.Apply(args)
if err != nil && strings.Contains(err.Error(), "expects true/false") {
	// surface exact cmd+flag from the message prefix to the user
}

Prevention

Only write literal true/false for boolean flags in crushrc files.
Check each builtin's flag spec (--help or docs) for expected value types.
Avoid quoting values so empty strings don't slip through.
Add a config linter/parse test for crushrc files in CI.

When it happens

Trigger: Writing a crushrc builtin invocation like `provider --debug yes` or `--verbose 1` where the flag was declared flagBool and parseBool only accepts true/false (Go strconv.ParseBool forms, per parseBool's implementation).

Common situations: Users copying CLI conventions from other tools that accept yes/no/1/0; typos like 'ture'; quoting mistakes that pass an empty string as the value.

Related errors

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