arg

Positional argument schema factory.

Entry point for defining args on a command. Use arg.<kind>() to create an ArgBuilder, then chain modifiers and pass the result to command().arg(name, builder).

Six base kinds are available:

• arg.string() — raw string (most common)
• arg.number() — parsed to number, errors on NaN
• arg.boolean() reads an explicit true/false token
• arg.enum(values) — constrained to listed literals
• arg.keyValue() merges KEY=VALUE tokens into a record
• arg.custom(fn) — arbitrary parse function, infers return type

Five sugar factories build on them, mirroring their flag counterparts:

• arg.url() parses to URL, with an optional protocol allowlist

• arg.path() keeps the string and adds optional filesystem checks

• arg.date() parses strict ISO-8601 to Date

• arg.duration() resolves '1h30m' and friends to milliseconds

• arg.bytes() resolves '512mb' and friends to bytes

• Import: @kjanat/dreamcli

• Export kind: constant

• Declared in: src/core/schema/arg.ts

• Source link: src/core/schema/arg.ts:1849

Signatures

const arg: ArgFactory;

Examples

import { command, arg } from '@kjanat/dreamcli';

command('deploy')
  .arg('target', arg.string().env('DEPLOY_TARGET').describe('Where to deploy'))
  .arg('port', arg.number().env('PORT').default(3000))
  .action(({ args }) => {
    console.log(`Deploying to ${args.target} on port ${args.port}`);
  });

// $ mycli deploy production 8080    → target='production', port=8080
// $ DEPLOY_TARGET=staging mycli deploy → target='staging', port=3000

Related Examples

• Basic single-command CLI. - examples/basic.ts
• Help rendering configuration. - examples/help-config.ts
• Interactive prompts with config file fallback. - examples/interactive.ts
• Mixed machine-readable JSON and human-readable side-channel output. - examples/json-mode.ts
• Middleware patterns: auth guard, request timing, error handling. - examples/middleware.ts
• Multi-command CLI with nested command groups (git-like). - examples/multi-command.ts
• Testing examples using @kjanat/dreamcli/testkit. - examples/testing.ts

See Also

• Examples overview
• Example Hover
• API overview
• @kjanat/dreamcli