{"id":"fe3ea9bb2d6abca0","repo":"yargs/yargs","slug":"usage-description-must-start-with-0-if-being-u","errorCode":null,"errorMessage":".usage() description must start with $0 if being used as alias for .command()","messagePattern":"\\.usage\\(\\) description must start with \\$0 if being used as alias for \\.command\\(\\)","errorType":"exception","errorClass":"YError","httpStatus":null,"severity":"error","filePath":"lib/yargs-factory.ts","lineNumber":1408,"sourceCode":"    msg: string | null,\n    description?: CommandHandler['description'],\n    builder?: CommandBuilderDefinition | CommandBuilder,\n    handler?: CommandHandlerCallback\n  ): YargsInstance {\n    argsert(\n      '<string|null|undefined> [string|boolean] [function|object] [function]',\n      [msg, description, builder, handler],\n      arguments.length\n    );\n\n    if (description !== undefined) {\n      assertNotStrictEqual(msg, null, this.#shim);\n      // .usage() can be used as an alias for defining\n      // a default command.\n      if ((msg || '').match(/^\\$0( |$)/)) {\n        return this.command(msg, description, builder, handler);\n      } else {\n        throw new YError(\n          '.usage() description must start with $0 if being used as alias for .command()'\n        );\n      }\n    } else {\n      this.#usage.usage(msg);\n      return this;\n    }\n  }\n  usageConfiguration(config: UsageConfiguration) {\n    argsert('<object>', [config], arguments.length);\n    this.#usageConfig = config;\n    return this;\n  }\n  version(opt?: string | false, msg?: string, ver?: string): YargsInstance {\n    const defaultVersionOpt = 'version';\n    argsert(\n      '[boolean|string] [string] [string]',\n      [opt, msg, ver],","sourceCodeStart":1390,"sourceCodeEnd":1426,"githubUrl":"https://github.com/yargs/yargs/blob/34d833aab18553aedee4b6cf5c1ad752eb8b8427/lib/yargs-factory.ts#L1390-L1426","documentation":"Thrown by YargsInstance.usage (lib/yargs-factory.ts:1408) when .usage(msg, description, ...) is called with a description (treating usage as an alias for .command()) but msg does not start with $0. When a description is provided, yargs interprets the call as defining a default command and requires the message to begin with $0 (the script-name placeholder); otherwise it cannot register a default command.","triggerScenarios":"Calling yargs.usage('deploy [env]', 'Deploy the app', builder, handler) - missing the $0 prefix. Mixing the two .usage() forms: the help-text form yargs.usage('$0 [options]') (no description) and the default-command form yargs.usage('$0 deploy [env]', 'desc', builder, handler).","commonSituations":"Trying to define a default command via .usage() without reading the $0 convention. Refactoring from .command('$0', ...) to .usage() and dropping the $0. Copy-pasting a usage string from a help banner into a default-command definition.","solutions":["Prefix the message with $0 when also passing a description: yargs.usage('$0 deploy [env]', 'Deploy the app', builder, handler).","If you only want to set help/usage text, omit the description argument entirely: yargs.usage('$0 [options]').","Prefer the explicit .command('$0 ...', desc, builder, handler) form to make the intent obvious."],"exampleFix":"// before\nyargs.usage('deploy [env]', 'Deploy the app', builder, handler);\n// after\nyargs.usage('$0 deploy [env]', 'Deploy the app', builder, handler);","handlingStrategy":"validation","validationCode":"function safeUsage(yargs, msg, description, builder, handler) {\n  if (description !== undefined && !/^\\$0( |$)/.test(msg || '')) {\n    throw new Error('.usage() default-command form requires msg to start with $0');\n  }\n  return yargs.usage(msg, description, builder, handler);\n}","typeGuard":"function isUsageDefaultCommandForm(\n  msg: unknown, description: unknown\n): boolean {\n  return description !== undefined && typeof msg === 'string' && /^\\$0( |$)/.test(msg);\n}","tryCatchPattern":"try {\n  yargs.usage(msg, description, builder, handler);\n} catch (e) {\n  if (e instanceof Error && /usage\\(\\) description must start with \\\\$0/.test(e.message)) {\n    console.error('usage-as-command requires a $0 prefix on the message');\n  } else {\n    throw e;\n  }\n}","preventionTips":["Reserve .usage(msg, description, ...) for the default-command form and always prefix msg with $0.","For pure help text, use .usage('$0 [options]') with no description.","Prefer explicit .command('$0 ...', desc, builder, handler) when in doubt."],"tags":["usage","command-registration","api-misuse","validation"],"analyzedSha":"34d833aab18553aedee4b6cf5c1ad752eb8b8427","analyzedAt":"2026-08-03T20:28:45.489Z","schemaVersion":2}