langgenius/dify · error · Error

unknown flag: -${char}

Error message

unknown flag: -${char}

What it means

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.

Source

Thrown at cli/src/framework/flags.ts:157

  def: FlagDefinition
  label: string
  inlineRaw: string | undefined
}

function resolveToken(token: string, flags: Record<string, FlagDefinition>): ResolvedFlag | null {
  if (token.startsWith('--')) {
    const eqIdx = token.indexOf('=')
    const name = eqIdx !== -1 ? token.slice(2, eqIdx) : token.slice(2)
    const inlineRaw = eqIdx !== -1 ? token.slice(eqIdx + 1) : undefined
    const def = flags[name]
    if (!def) throw new Error(`unknown flag: --${name}`)
    return { name, def, label: `--${name}`, inlineRaw }
  }

  if (token.length === 2 && token[1] !== undefined) {
    const char = token[1]
    const resolved = resolveByChar(char, flags)
    if (!resolved) throw new Error(`unknown flag: -${char}`)
    const [name, def] = resolved
    return { name, def, label: `-${char}`, inlineRaw: undefined }
  }

  return null
}

// Scans argv for a boolean flag without throwing on unknown tokens, so it is safe
// to call before the command-specific flag set is known (e.g. global flags).
export function hasBooleanFlag(argv: readonly string[], name: string, char?: string): boolean {
  for (const token of argv) {
    if (token === '--') break
    if (token === `--${name}` || token === `--${name}=true` || token === `--${name}=1`) return true
    if (char !== undefined && token === `-${char}`) return true
  }

  return false
}

View on GitHub (pinned to ef8544b173)

Solutions

1. Check `difyctl <cmd> --help` for the registered short flags (shown in [GLOBAL] and per-flag rows).
2. Use the long form to avoid ambiguity: `--verbose` instead of `-v` if unsure.
3. Verify there is no typo: only a single char after the dash is resolved here.

Example fix

// before
difyctl apps list -q

// after
difyctl apps list --verbose   // -v is the registered verbose short flag

// allowlist short flags your wrapper passes
const KNOWN_SHORT = new Set(['-v', '-o', '-h'])
function checkShortFlags(argv: string[]): void {
  for (const t of argv) {
    if (/^-[a-z]$/i.test(t) && !KNOWN_SHORT.has(t)) throw new Error(`unknown short flag ${t}`)
  }
}

function isKnownShortFlag(token: string, known: ReadonlySet<string>): boolean {
  return !/^-[a-z]$/i.test(token) || known.has(token)
}

When it happens

Trigger: `-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.

Common situations: 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.

Related errors

• unknown flag: --${name}
• flag ${label} expects a value
• UsageMissingArg
• expected integer, got ${JSON.stringify(raw)}
• expected boolean, got ${JSON.stringify(raw)}

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/d4a1578b247e11d2. Report an issue: GitHub.