Arguments Metadata
Padrone uses Zod schemas with .meta() to configure CLI-specific behavior. This reference covers all available metadata configuration.
Zod Meta Configuration
Section titled “Zod Meta Configuration”Use .meta() on individual Zod schema properties to configure their CLI behavior:
z.object({ output: z.string() .describe('Output file path') .meta({ flags: 'o', alias: 'out', examples: ['output.json', './dist/bundle.js'], }),})Available Meta Properties
Section titled “Available Meta Properties”| Property | Type | Description |
|---|---|---|
description |
string |
Help text for the option (the same as Zod’s .describe(), so .meta({ flags: 'o', description: 'Output file' }) takes one call) |
flags |
string | string[] |
Single-character short flags (e.g., 'p' for -p). Stackable: -abc = -a -b -c |
alias |
string | string[] |
Multi-character long aliases (e.g., 'dry-run' for --dry-run) |
negative |
string | string[] |
Custom negative keyword(s) for booleans. Disables --no- prefix |
examples |
unknown[] |
Example values shown in help |
deprecated |
string | boolean |
Mark as deprecated with optional message |
hidden |
boolean |
Hide from help output |
group |
string |
Group name for organizing under a labeled section in help output |
count |
boolean |
Count repeated flags into a number (-vvv → 3) |
variadic |
boolean |
Array option that takes every following value up to the next option (--tag a b c) |
fromFile |
boolean |
Command-line values can be @path (the file’s contents) or - (stdin); @@text passes @text |
conflicts |
string | string[] |
Options that can’t be used together with this one |
implies |
Record<string, unknown> |
Values for other options when this one is used |
requires |
string | string[] |
Options that must be provided when this one is |
requiredIf |
Record<string, unknown> | Record<string, unknown>[] |
Required when other options have these values (any object of an array) |
requiredUnless |
string | string[] |
Required unless one of these options is provided |
sensitive |
boolean |
Secret value: prompted without echo, default and examples hidden from help and tool schemas |
complete |
(ctx) => (string | { value, description? })[] | { values, directive? } (or a Promise) |
Values shell completion offers for this option or positional (fields config only; needs padroneCompletion()) |
hint |
'file' | 'dir' | 'url' | 'command' | 'none' | { ext: string[] } |
What shell completion falls back to for the value (see Value hints) |
valueName |
string |
Placeholder for the value in help and docs (--out <DIR>, <FILE> for a positional) |
Meta Configuration
Section titled “Meta Configuration”The second argument to .arguments() configures positional arguments and per-argument metadata:
.arguments(schema, { positional: ['source', '...files', 'dest'], fields: { verbose: { flags: 'v' }, dryRun: { alias: 'dry' }, format: { deprecated: 'Use --output instead' }, },})positional
Section titled “positional”Array of argument names to accept as positional arguments.
{ positional: ['source', 'dest'] }Positional argument order:
- Arguments are matched in the order specified
- Optional arguments are skipped if not provided
- An optional positional before required ones only takes a value when there are enough left for them: with
['method', 'url']andmethoddefaulting toGET,http https://xsetsurl, andhttp POST https://xsets both (like httpie’s[METHOD] URL) - Position matters:
['source', 'dest']means first arg is source, second is dest - Extra arguments are an error (
Too many arguments), as are positionals given to a command that declares none. Use a variadic (...rest) to accept any number
Variadic arguments:
- Prefix with
...to capture multiple values:['...files'] - Variadic args must be arrays in the schema:
z.array(z.string()) - Only one variadic argument is allowed per command
- Variadic can be at any position
// Capture all args between fixed positions{ positional: ['command', '...args', 'output'] }// command = first arg// args = all middle args// output = last argfields
Section titled “fields”Per-argument configuration that supplements or overrides .meta():
{ fields: { verbose: { flags: 'v' }, dryRun: { alias: 'dry' }, format: { deprecated: 'Use --output instead', hidden: true, }, },}This is equivalent to using .meta() on the schema property but allows configuration to be kept separate from the schema definition. Fields accept the same properties as Zod .meta(): flags, alias, negative, description, examples, deprecated, hidden, group, count, variadic, fromFile, conflicts, implies, requires, requiredIf, requiredUnless, sensitive, hint, valueName — plus complete, which only works here since functions don’t survive .meta().
autoAlias
Section titled “autoAlias”Automatically generate kebab-case aliases for camelCase argument names. Enabled by default.
// Default (autoAlias: true): --dry-run automatically maps to dryRun.arguments(z.object({ dryRun: z.boolean() }))
// Disable auto-aliases.arguments(z.object({ dryRun: z.boolean() }), { autoAlias: false })exactlyOne / atLeastOne
Section titled “exactlyOne / atLeastOne”Groups of options of which exactly one, or at least one, must be given. See Option groups.
.arguments(schema, { exactlyOne: ['file', 'url'], atLeastOne: ['email', 'slack'] })Read from stdin and inject the data into a specified argument field. Only reads when stdin is piped (not a TTY, including a custom runtime.stdin with isTTY: true) and the field wasn’t already provided via CLI flags, or when its value is a lone - (cat -, --data -; read even from a terminal). The read mode is inferred from the schema: string fields read all stdin as text, string[] fields read line-by-line. { field, trim: true } trims the text (each line, for arrays); number and boolean fields are always trimmed, so echo 21 | my-cli double works.
// Read all stdin as text into 'data' field.arguments(z.object({ data: z.string() }), { stdin: 'data' })
// Without the trailing newline.arguments(z.object({ token: z.string() }), { stdin: { field: 'token', trim: true } })
// Read stdin line-by-line into an array field (inferred from array schema).arguments( z.object({ lines: z.array(z.string()) }), { stdin: 'lines' })
// Stream stdin lazily as AsyncIterable (for large inputs)import { zodAsyncStream } from 'padrone/zod';.arguments( z.object({ lines: zodAsyncStream() }), { stdin: 'lines' })
// Typed stream with JSON codec (each line JSON.parse'd and validated)import { zodAsyncStream, jsonCodec } from 'padrone/zod';const itemSchema = z.object({ name: z.string(), age: z.number() });.arguments( z.object({ records: zodAsyncStream(jsonCodec(itemSchema)) }), { stdin: 'records' })interactive
Section titled “interactive”Declare which fields should be interactively prompted when their values are missing after CLI/env/config resolution. Only takes effect in cli() and eval() when the runtime has interactive: true.
// Prompt all missing required fields{ interactive: true }
// Prompt specific fields{ interactive: ['name', 'template'] }When interactive is set, parse() and cli() return Promises (the command becomes async).
Prompt types are auto-detected from the schema:
| Schema Type | Prompt |
|---|---|
z.boolean() |
Confirm (yes/no) |
z.enum([...]) |
Select (single choice) |
z.array(z.enum([...])) |
Multi-select |
z.string() |
Text input |
| Any other type | Text input |
The prompt message is derived from the field’s .describe() text, or from fields meta description, falling back to the field name.
optionalInteractive
Section titled “optionalInteractive”Additional fields offered after required interactive prompts. Users are shown a multi-select to choose which of these fields to configure.
// Offer all missing optional fields{ optionalInteractive: true }
// Offer specific fields{ optionalInteractive: ['verbose', 'format'] }Example combining both:
.arguments( z.object({ name: z.string().describe('Project name'), template: z.enum(['react', 'vue', 'svelte']).describe('Starter template'), typescript: z.boolean().default(false).describe('Use TypeScript'), eslint: z.boolean().default(false).describe('Add ESLint'), }), { positional: ['name'], interactive: ['name', 'template'], optionalInteractive: ['typescript', 'eslint'], })When running without arguments, this will:
- Prompt for
nameandtemplate(required interactive fields) - Show a multi-select: “Would you also like to configure: TypeScript, ESLint”
- Prompt individually for any selected optional fields
See the Interactive Prompting guide for full details.
Environment Variables
Section titled “Environment Variables”Bind arguments to environment variables using the padroneEnv extension:
import { createPadrone, padroneEnv } from 'padrone';import * as z from 'zod/v4';
const program = createPadrone('app') .command('serve', (c) => c .arguments( z.object({ port: z.number().default(3000), apiKey: z.string(), }), ) .extend( padroneEnv( z.object({ APP_PORT: z.coerce.number().optional(), API_KEY: z.string().optional(), }).transform((env) => ({ port: env.APP_PORT, apiKey: env.API_KEY, })) ) ) .action((args) => { console.log(`Server on port ${args.port}`); }), );The env schema validates process.env and transforms env var names into argument names. Only provided env values are used — undefined values are skipped, and a set but invalid value is reported as a validation error. padroneEnv can be applied at the program level (inherited by all commands) or at the command level.
Resolution priority:
- CLI argument (highest)
- Stdin
- Environment variable
- Config file
- Interactive prompt (if runtime supports it)
- Default value (lowest)
Config Files
Section titled “Config Files”Load arguments from configuration files using the padroneConfig extension:
import { createPadrone, padroneConfig } from 'padrone';import * as z from 'zod/v4';
const program = createPadrone('app') .command('serve', (c) => c .arguments( z.object({ port: z.number().default(3000), host: z.string().default('localhost'), }), ) .extend( padroneConfig({ files: 'app.config.json', schema: z.object({ port: z.number().optional(), host: z.string().optional(), }), }) ) .action((args) => { console.log(`Server on ${args.host}:${args.port}`); }), );Multiple config file paths can be provided in the files array — the first existing file is used:
.extend(padroneConfig({ files: ['app.config.json', '.apprc'] }))If no schema is provided, the config file values are matched against the command’s argument schema directly.
Short argument flags allow single-character shortcuts:
z.object({ verbose: z.boolean().optional().meta({ flags: 'v' }), port: z.number().default(3000).meta({ flags: 'p' }), output: z.string().optional().meta({ flags: 'o' }),})Usage:
app -v -p 8080 -o output.json# Equivalent to:app --verbose --port 8080 --output output.jsonCombined short flags:
app -vp 8080# -v (boolean) + -p 8080Aliases
Section titled “Aliases”Multi-character long aliases provide alternative names for arguments:
z.object({ dryRun: z.boolean().optional().meta({ alias: 'dry' }),})app --dry# Equivalent to:app --dry-run # (auto-alias from camelCase)app --dryRun # (original name)Custom Negation
Section titled “Custom Negation”By default, boolean arguments can be negated with the --no- prefix (e.g., --no-verbose). The negative meta option lets you define custom keyword(s) that set a boolean to false, while disabling the default --no- prefix:
z.object({ local: z.boolean().default(true).meta({ negative: 'remote' }),})app --remote# Equivalent to: local = false# --no-local is NOT recognized (disabled by custom negation)
app --local# local = true (still works normally)Multiple negative keywords:
z.object({ local: z.boolean().default(true).meta({ negative: ['remote', 'cloud'] }),})app --remote # local = falseapp --cloud # local = falseDisable --no- prefix only:
Set negative to an empty string or empty array to disable the --no- prefix without adding any alternative keywords:
z.object({ verbose: z.boolean().default(true).meta({ negative: '' }),})app --verbose # verbose = trueapp --no-verbose # Error: unknown optionCustom negation can also be set via fields meta:
.arguments(z.object({ local: z.boolean().default(true) }), { fields: { local: { negative: 'remote' } },})The stringify() method uses the first negative keyword when serializing false values:
program.stringify('cmd', { local: false })// → "cmd --remote" (instead of "cmd --no-local")Deprecation
Section titled “Deprecation”Mark arguments as deprecated to warn users:
.arguments( z.object({ // Simple deprecation old: z.string().optional().meta({ deprecated: true }), legacy: z.string().optional(), }), { // With a migration message (Zod's own `.meta()` type only allows a boolean here) fields: { legacy: { deprecated: 'Use --new-arg instead' } }, },)Deprecated arguments still work. They are marked in help, and using one from cli() or the REPL prints a warning to stderr, e.g. Warning: option "--legacy" is deprecated: Use --new-arg instead. Deprecated commands (.configure({ deprecated: 'Use "app build"' })) warn the same way.
Hidden Arguments
Section titled “Hidden Arguments”Hide arguments from help output while keeping them functional:
z.object({ // Visible in help port: z.number().default(3000),
// Hidden from help debug: z.boolean().optional().meta({ hidden: true }), internalFlag: z.string().optional().meta({ hidden: true }),})Hidden arguments:
- Don’t appear in
--helpoutput - Still work when specified
- Useful for internal/experimental features
Examples in Help
Section titled “Examples in Help”Provide example values for help text:
z.object({ format: z.enum(['json', 'csv', 'xml']) .describe('Output format') .meta({ examples: ['json', 'csv'] }),
date: z.string() .describe('Date filter') .meta({ examples: ['2024-01-01', 'today', 'last-week'] }),})Examples appear in the generated help text to guide users.
Groups
Section titled “Groups”Organize arguments into labeled sections in help output:
z.object({ port: z.number().default(3000).meta({ group: 'Server' }), host: z.string().default('localhost').meta({ group: 'Server' }), verbose: z.boolean().optional().meta({ group: 'Debug' }), logLevel: z.enum(['info', 'debug', 'warn']).optional().meta({ group: 'Debug' }),})Arguments with the same group name are displayed together under a labeled section in help output.
Counting Flags
Section titled “Counting Flags”count: true on a number option counts how often a flag is given instead of taking a value:
z.object({ verbose: z.number().default(0).meta({ flags: 'v', count: true }),})-vvv and -v -v --verbose give 3. --verbose=5 sets the count directly and --no-verbose resets it to 0. A counting flag never takes the next argument as its value. Help marks it (repeatable).
Variadic Options
Section titled “Variadic Options”By default an array option takes one value per flag (--tag a --tag b). With variadic: true it takes every following value up to the next option, --, or the end of input:
z.object({ tags: z.string().array().optional().meta({ flags: 't', variadic: true }), files: z.string().array().default([]),}) // with { positional: ['...files'] }--tags a b c --force gives tags: ['a', 'b', 'c']. Positionals after a variadic option need -- (--tags a b -- x.txt) or can come first (x.txt --tags a b). --tags=a takes a single value, and repeated flags keep accumulating. Help marks it (takes multiple values).
Values from Files
Section titled “Values from Files”fromFile: true on a string (or string array) option or positional, or an object option (read as JSON), lets its value be read from a file, like gh -F body=@file or curl -d @file:
.arguments(z.object({ title: z.string(), body: z.string() }), { positional: ['title'], fields: { body: { fromFile: true } },})--body @notes.mdreadsnotes.md(UTF-8, as is; relative to the working directory). A file that can’t be read is a validation error, e.g.body: Cannot read "notes.md": file not found.--body -(or@-) reads stdin, through the runtime’sstdin. Only one value per run can read stdin, and not when the command’sstdinfield would read it too (it doesn’t read a terminal, unless it’s a stream field or given-).--body @@mepasses@me: a leading@@escapes the@. Other values are taken as given.- For array options, each value is read on its own:
--tag @a.txt --tag b. - An object, record or array-of-objects option reads a JSON file:
--db @db.jsonparses the file’s JSON into the object (see Supported Types). - With
padroneResponseFiles(), an option’s@filevalue is still read byfromFile, not expanded as a response file. - Only values typed on the command line (
cli(),eval(), the REPL) are read. Values from env variables and config files, and args from serve, MCP andtool()calls, are taken literally, so a remote client can’t read the server’s files.
Help marks the option (@file or - for stdin). Reading stdin is async, so a command with a fromFile field in its fields meta is typed as async; set with .meta({ fromFile: true }) on the schema, mark the command .async().
Conflicting and Implied Options
Section titled “Conflicting and Implied Options”conflicts rejects options used together, and implies fills in other options when one is used:
z.object({ json: z.boolean().optional().meta({ conflicts: ['table'], implies: { color: false } }), table: z.boolean().optional(), color: z.boolean().optional(),})--json --tablefails withOption "--json" cannot be used with "--table". Declaring the conflict on either side is enough.--jsonsetscolortofalseunless--coloris given explicitly. An option set tofalse(e.g.--no-json) implies nothing.- Only options the user provided count: from the command line, stdin, env or config — not schema defaults or implied values.
Help shows (conflicts with --table) and (implies --no-color).
In the fields of .arguments(schema, meta), the options conflicts, implies, requires, requiredIf and requiredUnless name are type-checked against the schema’s options and the global ones, so a typo (conflicts: 'tabel') is a type error. In .meta() they’re plain strings.
Option groups
Section titled “Option groups”exactlyOne and atLeastOne in the arguments meta name a group of options (by field name). Pass an array of arrays for several groups:
.arguments(z.object({ file: z.string().optional(), url: z.string().optional(), stdin: z.boolean().optional() }), { exactlyOne: ['file', 'url', 'stdin'],})
.arguments(schema, { exactlyOne: [['json', 'yaml'], ['out', 'stdout']] })- No option given fails with
Exactly one of "--file", "--url", "--stdin" is required, two withOnly one of "--file", "--url" can be used. atLeastOneonly requires one of them:At least one of "--email", "--slack" is required.- Like
conflicts, only options the user provided count (command line, stdin, env, config), not schema defaults. .globalArgs(schema, { exactlyOne })applies the group in every command of the subtree, unless a command defines one of its fields itself.
Dependent options
Section titled “Dependent options”requires, requiredIf and requiredUnless make an option required depending on the others:
z.object({ user: z.string().optional().meta({ requires: 'password' }), password: z.string().optional(), token: z.string().optional().meta({ requiredUnless: ['user', 'key'] }), key: z.string().optional(), format: z.enum(['file', 'url', 'stdout']).default('stdout'), output: z.string().optional().meta({ requiredIf: [{ format: 'file' }, { format: 'url', ci: true }] }), ci: z.boolean().optional(),})--user mealone fails withOption "--user" requires "--password".- Without
--useror--key:Option "--token" is required unless one of "--user", "--key" is used. --format filewithout--output:Option "--output" is required when "--format" is "file". Every value of an object must match; with an array, any object.- They’re checked after
impliesand coercion: implied values count, andrequiredIfcompares typed values ({ port: 80 }matches--port 80). Schema defaults don’t count. - Each issue’s path is the missing option. With
interactivecovering it, the missing option is prompted instead. - They work in
.globalArgs()fields too. Help shows(requires --password),(required if --format=file or --format=url and --ci)and(required unless --user or --key).
Sensitive Values
Section titled “Sensitive Values”sensitive: true marks a secret such as a token or password:
z.object({ token: z.string().meta({ sensitive: true, description: 'API token' }),})- Interactive prompts ask for it without echo (
type: 'password') and never prefill it. - Help, generated docs and man pages don’t show its default or examples.
- MCP, serve and
tool()input schemas mark itwriteOnlywithoutdefaultorexamples. serve()rejects it in GET query strings (400), so it doesn’t end up in URLs and logs, and leaves it out of the OpenAPI GET parameters: send it in a POST body.- Padrone’s own error messages never include option values.
config list(frompadroneConfig({ command: true })) shows its value as[redacted].- Extensions that log or record args can call
redactArgs(command, args)(from'padrone'): a copy with sensitive fields, nested and global ones included, replaced by'[redacted]'.
Completion Values
Section titled “Completion Values”With padroneCompletion() applied, the generated shell scripts ask the program for candidates on each tab press, so completion follows the command being typed: its subcommands, its own options and inherited global options, and values for the option or positional under the cursor. Enum values are offered automatically; complete supplies values computed at completion time:
import { padroneCompletion } from 'padrone/completion';
createPadrone('git') .extend(padroneCompletion()) .command('checkout', (c) => c.arguments(z.object({ branch: z.string() }), { positional: ['branch'], fields: { branch: { complete: async ({ prefix, args, command }) => listBranches() } }, }), );The callback receives the word typed so far (prefix), the options typed before it (args, parsed but not validated), the command path, the field being completed, the runtime and the context passed to cli() (with the commands’ .context() transforms applied). Return candidates unfiltered or filtered, it’s up to you: only those starting with the prefix are shown. Errors are swallowed so a failing lookup never breaks the shell.
Return { values, directive } to also say what the shell falls back to when nothing matches: 'files', 'dirs', 'ext:json,yaml', 'commands' or 'nofiles' (see Value hints):
complete: async ({ prefix }) => ({ values: await listRemotes(prefix), directive: 'nofiles' }),Command-level completion
Section titled “Command-level completion”.configure({ complete }) completes a command’s positionals in one place, like cobra’s ValidArgsFunction. It’s called for each positional word with its position (0-based), the positional field at that position (if any) and the positionals typed before it; a positional field’s own complete wins over it, and subcommand names are still offered next to its values:
createPadrone('kube') .extend(padroneCompletion()) .command('get', (c) => c .arguments(z.object({ kind: z.string(), names: z.string().array().optional() }), { positional: ['kind', '...names'] }) .configure({ complete: ({ position, positionals, runtime }) => position === 0 ? ['pods', 'services'] : listResources(positionals[0], runtime.env().KUBE_NAMESPACE), }) .action(/* ... */), );Option names are offered as help shows them: --dry-run for a dryRun field (typing --dryRun still works), and short flags (-f) too when the word is - or -f. Hidden commands and options are never offered; deprecated ones only when nothing else matches what’s typed (--old for a deprecated --old-region). The static scripts leave out hidden and deprecated ones too.
Candidates can carry a description, which zsh, fish and PowerShell show next to the value (bash shows values only). Subcommands and options are described with their descriptions, and literal unions (z.union([z.literal('eu').describe('Europe'), ...])) with each literal’s:
complete: () => [{ value: 'main', description: 'Default branch' }, 'develop'],Value hints
Section titled “Value hints”When no candidate matches, the shell falls back to file names for a value without enum values or complete (a value with candidates gets no fallback). hint says what to complete instead:
z.object({ config: z.string().meta({ hint: { ext: ['json', 'yaml'] } }), // *.json, *.yaml and directories out: z.string().meta({ hint: 'dir', valueName: 'DIR' }), // directories editor: z.string().meta({ hint: 'command' }), // program names url: z.string().meta({ hint: 'url' }), // nothing ('none' too) input: z.string().meta({ hint: 'file' }), // files, even with enum values or complete});Boolean flags never complete a value. The static scripts (without padroneCompletion()) follow hint for options too.
valueName is the value placeholder in help: --out <DIR> instead of --out <string>, and <DIR> instead of the field name for a positional. Markdown, HTML and JSON help, generated docs and man pages use it too.
The __complete2 protocol
Section titled “The __complete2 protocol”Scripts are generated with git completion <shell>. On each tab press they call git __complete2 <words> (the words after the program name, the last being the word under the cursor), which you can run by hand to debug. It prints one candidate per line, value<TAB>description or just value, then a directive for when nothing matches: :files, :dirs, :ext:json,yaml, :commands or :nofiles.
$ git __complete2 checkout ''main Default branchdevelop:nofilesA last word of "" counts as empty: Windows PowerShell 5.1 drops empty arguments to programs, so the PowerShell script passes "" for a word not typed yet.
git completion <shell> --instructions prints how to install the script for that shell (for the detected shell without one) instead of the script.
git __complete <words> prints values only, one per line, as scripts generated by earlier versions expect. Regenerate those scripts to get descriptions and hints; the eval "$(git completion bash)" line that completion --setup installs does so on each shell start.