{"record":{"id":"d4a1578b247e11d2","repo":"langgenius/dify","slug":"unknown-flag-char","errorCode":null,"errorMessage":"unknown flag: -${char}","messagePattern":"unknown flag: -(.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/framework/flags.ts","lineNumber":157,"sourceCode":"  def: FlagDefinition\n  label: string\n  inlineRaw: string | undefined\n}\n\nfunction resolveToken(token: string, flags: Record<string, FlagDefinition>): ResolvedFlag | null {\n  if (token.startsWith('--')) {\n    const eqIdx = token.indexOf('=')\n    const name = eqIdx !== -1 ? token.slice(2, eqIdx) : token.slice(2)\n    const inlineRaw = eqIdx !== -1 ? token.slice(eqIdx + 1) : undefined\n    const def = flags[name]\n    if (!def) throw new Error(`unknown flag: --${name}`)\n    return { name, def, label: `--${name}`, inlineRaw }\n  }\n\n  if (token.length === 2 && token[1] !== undefined) {\n    const char = token[1]\n    const resolved = resolveByChar(char, flags)\n    if (!resolved) throw new Error(`unknown flag: -${char}`)\n    const [name, def] = resolved\n    return { name, def, label: `-${char}`, inlineRaw: undefined }\n  }\n\n  return null\n}\n\n// Scans argv for a boolean flag without throwing on unknown tokens, so it is safe\n// to call before the command-specific flag set is known (e.g. global flags).\nexport function hasBooleanFlag(argv: readonly string[], name: string, char?: string): boolean {\n  for (const token of argv) {\n    if (token === '--') break\n    if (token === `--${name}` || token === `--${name}=true` || token === `--${name}=1`) return true\n    if (char !== undefined && token === `-${char}`) return true\n  }\n\n  return false\n}","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/framework/flags.ts#L139-L175","documentation":"Companion to [45]: a bare Error from resolveToken (flags.ts:157) for single-dash short flags. The branch only fires for tokens of exactly length 2 starting with '-' (so `-abc` clusters and `--` are NOT handled here). It calls resolveByChar to match def.char; no match → throw. Only `-v` (VERBOSE_CHAR) is global. Plain Error, no BaseError routing.","triggerScenarios":"`-z`, `-x`, `-q` when no command flag has that char. Most commands only define a handful of short flags; mistyping is the usual cause. Note `-h`/`--help` handling depends on the command class, not this resolver.","commonSituations":"Confusing difyctl short flags with another tool's (git, npm); pressing the wrong key; assuming common short flags like -q (quiet) or -f (force) exist when they don't.","solutions":["Check `difyctl <cmd> --help` for the registered short flags (shown in [GLOBAL] and per-flag rows).","Use the long form to avoid ambiguity: `--verbose` instead of `-v` if unsure.","Verify there is no typo: only a single char after the dash is resolved here."],"exampleFix":"// before\ndifyctl apps list -q\n\n// after\ndifyctl apps list --verbose   // -v is the registered verbose short flag","handlingStrategy":"validation","validationCode":"// allowlist short flags your wrapper passes\nconst KNOWN_SHORT = new Set(['-v', '-o', '-h'])\nfunction checkShortFlags(argv: string[]): void {\n  for (const t of argv) {\n    if (/^-[a-z]$/i.test(t) && !KNOWN_SHORT.has(t)) throw new Error(`unknown short flag ${t}`)\n  }\n}","typeGuard":"function isKnownShortFlag(token: string, known: ReadonlySet<string>): boolean {\n  return !/^-[a-z]$/i.test(token) || known.has(token)\n}","tryCatchPattern":null,"preventionTips":["Use long forms in scripts to sidestep short-flag ambiguity entirely.","When passing short flags, double-check the char against --help."],"tags":["cli","flags","unknown-flag","short-flag","usage"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}