Type Flag

type-flag

Quick start

import { typeFlag } from 'type-flag'

const parsed = typeFlag({
    name: String,
    age: { type: Number, alias: 'a' },
})

// $ my-cli --name John -a 20
parsed.flags.name   // 'John'
parsed.flags.age    // 20
parsed.unknownFlags // {}
parsed._            // []  (positional args, with _['--'] for post-`--`)

Schema

Type options:

Custom parsers & Standard Schema

A flag type is any (value: string) => T; the return type becomes the flag type. Use it to validate, narrow, or transform:

const Size = (value: string) => {
    if (value !== 'small' && value !== 'large') {
        throw new Error(`Invalid size: ${value}`)
    }
    return value as 'small' | 'large'
}

typeFlag({ size: Size }) // flags.size: 'small' | 'large' | undefined

Or pass a Standard Schema (Zod, Valibot, ArkType) directly — type-flag validates it and infers the flag type from the schema's output, no wrapper:

typeFlag({
    size: z.enum(['small', 'large']), // 'small' | 'large' | undefined
    port: z.coerce.number(),          // number | undefined
    tags: [z.string()],               // string[]
})

• Multiple values: wrap in [schema], NOT z.array(...) (it validates a single token and throws).
• Numbers: CLI values are strings, so coerce (z.coerce.number()).
• Booleans: keep native Boolean (a schema loses --no- negation and short grouping).
• Sync only: async schemas throw. A failed schema or parser propagates the raw error.

Return shape

{
    flags:        { [name]: InferredType },
    unknownFlags: { [name]: (string | boolean)[] },  // not camelCased
    _:            string[] & { '--': string[] },      // positional; everything after `--` also in `_['--']`
}

Flag forms

Single-char flag names vs aliases

Both produce short flags that group identically (-ab, -av, mixed — all work). The difference is OUTPUT placement:

Single-char names match -x but NOT --x — this preserves schemas like { h: Boolean, help: Boolean } where -h and --help must stay distinct (rg-style short-vs-long help).

Boolean negation (opt-in)

typeFlag({ verbose: Boolean }, argv, { booleanNegation: true })
// --no-verbose  → flags.verbose = false
// --verbose --no-verbose → false (last wins)

Only affects Boolean-typed, schema-known flags. --no-X for non-boolean or unknown falls through to unknownFlags.

Explicit =false always works regardless of booleanNegation:

// --verbose=false → flags.verbose = false
// --verbose false → flags.verbose = true, `_` = ['false']  (space-separated is positional)

ignore callback

Skip parsing specific tokens (leave them in argv). Called for each token:

ignore?: (
    type: 'known-flag' | 'unknown-flag' | 'argument',
    flagOrArgv: string,
    value: string | undefined,
) => boolean | void

Two common patterns:

// 1. Leave unknown flags in argv (e.g. forward to child process)
typeFlag({}, argv, { ignore: type => type === 'unknown-flag' })

// 2. Stop parsing at first positional (Node-style subcommand dispatch)
let stop = false
typeFlag(schema, argv, {
    ignore: (type) => {
        if (stop) return true
        if (type === 'argument') { stop = true; return true }
    },
})

argv is mutated: type-flag removes parsed tokens. Pass process.argv.slice(2) (or a copy) to see what's left.

getFlag — one-off extraction

import { getFlag } from 'type-flag'

const name = getFlag('--name', String)          // single value
const age  = getFlag('-a,--age', Number)        // comma-separated names
const tags = getFlag('-t,--tag', [String])      // array form collects all

Same argv-mutation behavior as typeFlag.

Gotchas

Related

For full CLI framework with help generation and subcommands, see cleye (built on type-flag).