iOfficeAI/OfficeCLI · error · CliException

invalid_argument

invalid_argument

Error message

Unrecognized option '{token}'.

What it means

Thrown by RejectUnknownOptionTokens when a command-line token starting with '--' (length > 2) is not a recognized option, was not already claimed as a missing-prop warning, and is not the 'prop'/'props' typo form. This hard-rejects unmatched flags that System.CommandLine would otherwise silently swallow (exit 0 with the element misplaced). It is a CliException with Code=invalid_argument and a Suggestion pointing at --prop.

Source

Thrown at src/officecli/CommandBuilder.cs:1588

    {
        var tokens = parseResult.UnmatchedTokens;
        var claimedKeys = new HashSet<string>(
            claimedKeyValues.Select(kv => kv.Split('=', 2)[0].Trim().TrimStart('-')),
            StringComparer.OrdinalIgnoreCase);
        for (int i = 0; i < tokens.Count; i++)
        {
            var token = tokens[i];
            if (token == "--") break;                       // explicit passthrough separator
            if (!token.StartsWith("--") || token.Length <= 2) continue;
            var key = token[2..];
            if (key.Contains('='))                          // --key=value form
                key = key[..key.IndexOf('=')];
            if (claimedKeys.Contains(key)) continue;        // already warned as missing --prop
            if (key is "props" or "prop") continue;         // typo forms handled above
            var valueHint = i + 1 < tokens.Count && !tokens[i + 1].StartsWith("--")
                ? $"{key}={tokens[i + 1]}"
                : $"{key}=<value>";
            throw new OfficeCli.Core.CliException($"Unrecognized option '{token}'.")
            {
                Code = "invalid_argument",
                Suggestion = $"Element properties are passed via --prop, e.g. --prop {valueHint}. Run 'officecli add --help' for the supported options."
            };
        }
    }

    /// <summary>
    /// Reduce a Word handler result path to the meaningful scope label for
    /// UNSUPPORTED messages — "/styles", "/body/p[N]", "/body/p[N]/r[N]".
    /// Stops at the first segment that is not a known top-level Word
    /// container so unfamiliar paths fall back to the full path.
    /// </summary>
    private static string ScopeLabelForWordPath(string path)
    {
        if (string.IsNullOrEmpty(path)) return "/";
        if (path.StartsWith("/styles/", StringComparison.Ordinal)) return "/styles";
        // Trim everything past the last bracketed-segment we recognize for

View on GitHub (pinned to 1ced45e900)

Solutions

1. Run 'officecli <command> --help' and replace the unknown flag with a supported one.
2. If the value is an element property, move it under '--prop key=value' rather than a top-level flag.
3. If the token was meant as a literal value (not a flag), pass it positionally or quote it so it does not start with '--'.

Example fix

# before
officecli add /slide[1] --type shape --colour FF0000
# after
officecli add /slide[1] --type shape --prop fill=#FF0000

// before invoking, confirm every --flag is a known option
foreach (var tok in parseResult.UnmatchedTokens)
{
    if (tok.StartsWith("--") && tok.Length > 2 && !KnownOptions.Contains(tok.TrimStart('-').Split('=')[0]))
        throw new CliException($"Unrecognized option '{tok}'.") { Code = "invalid_argument" };
}

static bool IsKnownOption(string token, IEnumerable<string> known) =>
    !token.StartsWith("--") || token.Length <= 2 ||
    known.Contains(token[2..].Split('=')[0], StringComparer.OrdinalIgnoreCase);

try { RejectUnknownOptionTokens(parseResult, claimed); }
catch (CliException ex) when (ex.Code == "invalid_argument")
{ /* ex.Suggestion names the --prop alternative; surface to user */ }

When it happens

Trigger: Calling e.g. 'officecli add /slide[1] --type shape --at A2' where --at is not a real option. A typo like '--tpye' instead of '--type'. A flag meant for a different subcommand.

Common situations: A user typos an option name. A caller assumes an option exists from another subcommand. An agent invents a flag (--position, --where) that the command does not accept.

Related errors

• Invalid --prop '{prop}': key is empty. Use key=value (e.g. -
• invalid_argument
• missing_argument
• batch: --commands and --input are mutually exclusive. Pick o
• Input file not found: {inputFile.FullName}

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/da5a66dcd94e5c3e. Report an issue: GitHub.