{"record":{"id":"da5a66dcd94e5c3e","repo":"iOfficeAI/OfficeCLI","slug":"invalid-argument-da5a66","errorCode":"invalid_argument","errorMessage":"Unrecognized option '{token}'.","messagePattern":"Unrecognized option '(.+?)'\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/CommandBuilder.cs","lineNumber":1588,"sourceCode":"    {\n        var tokens = parseResult.UnmatchedTokens;\n        var claimedKeys = new HashSet<string>(\n            claimedKeyValues.Select(kv => kv.Split('=', 2)[0].Trim().TrimStart('-')),\n            StringComparer.OrdinalIgnoreCase);\n        for (int i = 0; i < tokens.Count; i++)\n        {\n            var token = tokens[i];\n            if (token == \"--\") break;                       // explicit passthrough separator\n            if (!token.StartsWith(\"--\") || token.Length <= 2) continue;\n            var key = token[2..];\n            if (key.Contains('='))                          // --key=value form\n                key = key[..key.IndexOf('=')];\n            if (claimedKeys.Contains(key)) continue;        // already warned as missing --prop\n            if (key is \"props\" or \"prop\") continue;         // typo forms handled above\n            var valueHint = i + 1 < tokens.Count && !tokens[i + 1].StartsWith(\"--\")\n                ? $\"{key}={tokens[i + 1]}\"\n                : $\"{key}=<value>\";\n            throw new OfficeCli.Core.CliException($\"Unrecognized option '{token}'.\")\n            {\n                Code = \"invalid_argument\",\n                Suggestion = $\"Element properties are passed via --prop, e.g. --prop {valueHint}. Run 'officecli add --help' for the supported options.\"\n            };\n        }\n    }\n\n    /// <summary>\n    /// Reduce a Word handler result path to the meaningful scope label for\n    /// UNSUPPORTED messages — \"/styles\", \"/body/p[N]\", \"/body/p[N]/r[N]\".\n    /// Stops at the first segment that is not a known top-level Word\n    /// container so unfamiliar paths fall back to the full path.\n    /// </summary>\n    private static string ScopeLabelForWordPath(string path)\n    {\n        if (string.IsNullOrEmpty(path)) return \"/\";\n        if (path.StartsWith(\"/styles/\", StringComparison.Ordinal)) return \"/styles\";\n        // Trim everything past the last bracketed-segment we recognize for","sourceCodeStart":1570,"sourceCodeEnd":1606,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/CommandBuilder.cs#L1570-L1606","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run 'officecli <command> --help' and replace the unknown flag with a supported one.","If the value is an element property, move it under '--prop key=value' rather than a top-level flag.","If the token was meant as a literal value (not a flag), pass it positionally or quote it so it does not start with '--'."],"exampleFix":"# before\nofficecli add /slide[1] --type shape --colour FF0000\n# after\nofficecli add /slide[1] --type shape --prop fill=#FF0000","handlingStrategy":"validation","validationCode":"// before invoking, confirm every --flag is a known option\nforeach (var tok in parseResult.UnmatchedTokens)\n{\n    if (tok.StartsWith(\"--\") && tok.Length > 2 && !KnownOptions.Contains(tok.TrimStart('-').Split('=')[0]))\n        throw new CliException($\"Unrecognized option '{tok}'.\") { Code = \"invalid_argument\" };\n}","typeGuard":"static bool IsKnownOption(string token, IEnumerable<string> known) =>\n    !token.StartsWith(\"--\") || token.Length <= 2 ||\n    known.Contains(token[2..].Split('=')[0], StringComparer.OrdinalIgnoreCase);","tryCatchPattern":"try { RejectUnknownOptionTokens(parseResult, claimed); }\ncatch (CliException ex) when (ex.Code == \"invalid_argument\")\n{ /* ex.Suggestion names the --prop alternative; surface to user */ }","preventionTips":["Run '<command> --help' and keep the supported option list.","Move element properties under '--prop key=value' rather than inventing flags.","Treat any unmatched '--' token as a likely typo, not a silent no-op."],"tags":["cli","option","invalid-argument","parse"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}