Argument Parsing Patterns

Advanced patterns for argument parsing across Node.js, Python, Go, and Rust. Load this file only when the task requires patterns beyond basic flags and positional arguments.

Variadic arguments

Accept a variable number of positional arguments.

Node.js (Commander.js)

program
  .command('concat')
  .description('Concatenate multiple files')
  .argument('<files...>', 'one or more file paths')
  .action((files: string[]) => {
    // files is an array: ['a.txt', 'b.txt', 'c.txt']
    for (const file of files) {
      process.stdout.write(readFileSync(file));
    }
  });

Python (click)

@cli.command()
@click.argument("files", nargs=-1, required=True, type=click.Path(exists=True))
def concat(files):
    """Concatenate multiple files."""
    for f in files:
        click.echo(open(f).read(), nl=False)

Go (cobra)

var concatCmd = &cobra.Command{
    Use:   "concat <file> [file...]",
    Short: "Concatenate multiple files",
    Args:  cobra.MinimumNArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        for _, path := range args {
            data, err := os.ReadFile(path)
            if err != nil { return err }
            cmd.OutOrStdout().Write(data)
        }
        return nil
    },
}

Rust (clap)

#[derive(Parser)]
struct Concat {
    /// One or more file paths
    #[arg(required = true, num_args = 1..)]
    files: Vec<PathBuf>,
}

Mutually exclusive flags

Prevent the user from passing conflicting options.

Node.js (Commander.js) - no built-in support, validate manually:

program
  .command('output')
  .option('--json', 'output as JSON')
  .option('--csv', 'output as CSV')
  .option('--table', 'output as table')
  .action((options) => {
    const formats = [options.json, options.csv, options.table].filter(Boolean);
    if (formats.length > 1) {
      console.error('Error: --json, --csv, and --table are mutually exclusive.');
      process.exit(2);
    }
    const format = options.json ? 'json' : options.csv ? 'csv' : 'table';
    render(format);
  });

Python (click) - use cls=MutuallyExclusiveOption or manual check:

@cli.command()
@click.option("--json", "fmt", flag_value="json", help="Output as JSON.")
@click.option("--csv", "fmt", flag_value="csv", help="Output as CSV.")
@click.option("--table", "fmt", flag_value="table", default=True, help="Output as table.")
def output(fmt):
    """Render output in the chosen format."""
    render(fmt)

Go (cobra) - use MarkFlagsMutuallyExclusive:

outputCmd.Flags().Bool("json", false, "output as JSON")
outputCmd.Flags().Bool("csv", false, "output as CSV")
outputCmd.MarkFlagsMutuallyExclusive("json", "csv")

Rust (clap) - use conflicts_with:

#[derive(Parser)]
struct Output {
    #[arg(long, conflicts_with = "csv")]
    json: bool,
    #[arg(long, conflicts_with = "json")]
    csv: bool,
}

Custom type coercion

Parse flag values into specific types with validation.

Node.js (Commander.js) - custom parsing function:

function parsePort(value: string): number {
  const port = parseInt(value, 10);
  if (isNaN(port) || port < 1 || port > 65535) {
    throw new InvalidArgumentError('Port must be between 1 and 65535.');
  }
  return port;
}

program
  .option('-p, --port <number>', 'server port', parsePort, 3000);

Python (click) - use click.IntRange or custom ParamType:

@click.option("--port", type=click.IntRange(1, 65535), default=3000, help="Server port.")
def serve(port):
    start_server(port)

Go (cobra + pflag) - implement pflag.Value interface:

type portValue uint16

func (p *portValue) String() string { return fmt.Sprintf("%d", *p) }
func (p *portValue) Set(s string) error {
    v, err := strconv.ParseUint(s, 10, 16)
    if err != nil || v < 1 || v > 65535 {
        return fmt.Errorf("port must be between 1 and 65535")
    }
    *p = portValue(v)
    return nil
}
func (p *portValue) Type() string { return "port" }

Rust (clap) - use value_parser:

#[arg(short, long, default_value_t = 3000, value_parser = clap::value_parser!(u16).range(1..=65535))]
port: u16,

Required flags vs required positional args

Rule of thumb: if there is one primary input, make it positional. If there are multiple required inputs with no natural order, make them required options.

# Good: single primary input as positional
mytool compile <file>

# Good: multiple required inputs as named options
mytool deploy --env staging --tag v1.2.3

# Bad: multiple positionals with no obvious order
mytool deploy staging v1.2.3    # which is env, which is tag?

Flag groups and conditional requirements

Go (cobra) - require flags together:

cmd.MarkFlagsRequiredTogether("username", "password")
cmd.MarkFlagRequired("config")

Rust (clap) - require conditionally:

#[arg(long, requires = "password")]
username: Option<String>,
#[arg(long, requires = "username")]
password: Option<String>,

Node.js / Python - validate manually in the action handler. Check for incomplete flag groups and print a clear error:

if (options.username && !options.password) {
  console.error('Error: --username requires --password.');
  process.exit(2);
}

Negatable flags

Allow users to explicitly disable a default-on behavior.

Node.js (Commander.js):

program
  .option('--color', 'enable colored output (default)')
  .option('--no-color', 'disable colored output');
// options.color is true by default, false if --no-color is passed

Python (click):

@click.option("--color/--no-color", default=True, help="Toggle colored output.")

Rust (clap):

#[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
color: bool,

Environment variable fallback

Let environment variables serve as defaults for flags the user does not pass.

Node.js (Commander.js) - use envVar or manual fallback:

program
  .option('--api-key <key>', 'API key')
  .action((options) => {
    const apiKey = options.apiKey ?? process.env.MYTOOL_API_KEY;
    if (!apiKey) {
      console.error('Error: --api-key or MYTOOL_API_KEY is required.');
      process.exit(2);
    }
  });

Python (click) - use envvar parameter:

@click.option("--api-key", envvar="MYTOOL_API_KEY", required=True, help="API key.")

Go (cobra + viper) - bind flags to env vars via viper:

viper.SetEnvPrefix("MYTOOL")
viper.AutomaticEnv()
viper.BindPFlag("api-key", cmd.Flags().Lookup("api-key"))

Rust (clap) - use env:

#[arg(long, env = "MYTOOL_API_KEY")]
api_key: String,

Library comparison matrix

Config File Patterns

Patterns for managing CLI configuration files across multiple scopes and formats. Load this file only when the task involves config loading, dotfiles, XDG compliance, or config schema validation.

XDG Base Directory Specification

The XDG spec defines where config, data, cache, and state files live on Linux and macOS. Following it keeps user home directories clean.

Config path resolution:

import { join } from 'path';
import { homedir } from 'os';

function configDir(toolName: string): string {
  return join(
    process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'),
    toolName
  );
}

function dataDir(toolName: string): string {
  return join(
    process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'),
    toolName
  );
}

function cacheDir(toolName: string): string {
  return join(
    process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'),
    toolName
  );
}

Python:

from pathlib import Path
import os

def config_dir(tool: str) -> Path:
    base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
    return base / tool

def data_dir(tool: str) -> Path:
    base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
    return base / tool

Config file formats

JSON

{
  "output": "dist",
  "verbose": false,
  "plugins": ["@mytool/plugin-a"]
}

Pros: universal parser support, strict syntax. Cons: no comments, no trailing commas.

YAML

output: dist
verbose: false
plugins:
  - "@mytool/plugin-a"

Pros: human-readable, supports comments. Cons: indentation sensitivity, security risks with !! tags.

TOML

output = "dist"
verbose = false
plugins = ["@mytool/plugin-a"]

Pros: clear section boundaries, typed values, comments. Cons: less familiar to web developers, verbose for nested structures.

JavaScript / TypeScript

// mytool.config.ts
import type { Config } from 'mytool';

export default {
  output: 'dist',
  verbose: false,
  plugins: ['@mytool/plugin-a'],
} satisfies Config;

Pros: type checking, dynamic values, IDE autocompletion. Cons: security risk (arbitrary code execution), harder to lint.

Recommendation

Offer JSON and YAML at minimum. Add TypeScript config support for developer tools. Use cosmiconfig (Node.js) or dynaconf (Python) to search multiple formats automatically.

Full config loading hierarchy

A production CLI should merge config from all sources in this order:

import { cosmiconfig } from 'cosmiconfig';
import { z } from 'zod';

// 1. Define schema
const ConfigSchema = z.object({
  output: z.string().default('dist'),
  verbose: z.boolean().default(false),
  timeout: z.number().int().positive().default(30000),
  plugins: z.array(z.string()).default([]),
});

type Config = z.infer<typeof ConfigSchema>;

// 2. Load and merge
async function resolveConfig(cliFlags: Partial<Config>): Promise<Config> {
  const explorer = cosmiconfig('mytool');
  const result = await explorer.search();

  const merged = {
    // Layer 1: hardcoded defaults (handled by zod .default())
    // Layer 2: file config
    ...result?.config,
    // Layer 3: environment variables
    ...(process.env.MYTOOL_OUTPUT ? { output: process.env.MYTOOL_OUTPUT } : {}),
    ...(process.env.MYTOOL_VERBOSE ? { verbose: process.env.MYTOOL_VERBOSE === 'true' } : {}),
    ...(process.env.MYTOOL_TIMEOUT ? { timeout: parseInt(process.env.MYTOOL_TIMEOUT, 10) } : {}),
    // Layer 4: CLI flags (highest priority)
    ...Object.fromEntries(
      Object.entries(cliFlags).filter(([, v]) => v !== undefined)
    ),
  };

  // 3. Validate
  const parsed = ConfigSchema.safeParse(merged);
  if (!parsed.success) {
    console.error('Invalid configuration:');
    for (const issue of parsed.error.issues) {
      console.error(`  ${issue.path.join('.')}: ${issue.message}`);
    }
    process.exit(2);
  }

  return parsed.data;
}

Environment variable conventions

Follow these naming rules for environment variables:

Python (click) auto-mapping:

@click.option("--output", envvar="MYTOOL_OUTPUT", default="dist")
@click.option("--verbose", envvar="MYTOOL_VERBOSE", is_flag=True)

Rust (clap) auto-mapping:

#[arg(long, env = "MYTOOL_OUTPUT", default_value = "dist")]
output: String,

Schema validation

Always validate config files at load time. Report all errors at once rather than failing on the first one.

Node.js (zod):

const parsed = ConfigSchema.safeParse(rawConfig);
if (!parsed.success) {
  console.error('Config validation failed:');
  for (const issue of parsed.error.issues) {
    console.error(`  ${issue.path.join('.')}: ${issue.message}`);
  }
  process.exit(2);
}

Python (pydantic):

from pydantic import BaseModel, ValidationError

class Config(BaseModel):
    output: str = "dist"
    verbose: bool = False
    timeout: int = 30000
    plugins: list[str] = []

try:
    config = Config(**raw_config)
except ValidationError as e:
    for err in e.errors():
        click.echo(f"  {'.'.join(str(l) for l in err['loc'])}: {err['msg']}", err=True)
    raise SystemExit(2)

Config migration

When the config schema changes between versions, provide an automatic migration path.

interface Migration {
  from: string;  // semver range
  to: string;
  migrate: (config: Record<string, unknown>) => Record<string, unknown>;
}

const migrations: Migration[] = [
  {
    from: '1.x',
    to: '2.0.0',
    migrate: (config) => {
      // Renamed "outDir" to "output" in v2
      if ('outDir' in config) {
        config.output = config.outDir;
        delete config.outDir;
      }
      return config;
    },
  },
];

function migrateConfig(
  config: Record<string, unknown>,
  fromVersion: string
): Record<string, unknown> {
  let current = config;
  for (const m of migrations) {
    if (satisfies(fromVersion, m.from)) {
      console.error(`Migrating config from ${m.from} to ${m.to}...`);
      current = m.migrate(current);
    }
  }
  return current;
}

Config file creation / init command

Provide a init or config subcommand that creates a config file interactively or with sensible defaults.

program
  .command('init')
  .description('Create a configuration file')
  .option('--format <format>', 'config format (json, yaml, toml)', 'json')
  .action(async (options) => {
    const configPath = `.mytoolrc.${options.format}`;

    if (existsSync(configPath)) {
      console.error(`Error: ${configPath} already exists.`);
      process.exit(1);
    }

    const defaults = {
      output: 'dist',
      verbose: false,
      plugins: [],
    };

    const content = options.format === 'json'
      ? JSON.stringify(defaults, null, 2)
      : options.format === 'yaml'
      ? dumpYaml(defaults)
      : dumpToml(defaults);

    writeFileSync(configPath, content + '\n');
    console.log(`Created ${configPath}`);
  });

Platform-specific config paths

Use a library like env-paths (Node.js) or dirs (Rust) to resolve platform-specific paths automatically:

import envPaths from 'env-paths';
const paths = envPaths('mytool', { suffix: '' });
// paths.config -> platform-appropriate config dir
// paths.data   -> platform-appropriate data dir
// paths.cache  -> platform-appropriate cache dir

use dirs::config_dir;
let config = config_dir().unwrap().join("mytool").join("config.toml");