std.cli | Zero

When To Use std.cli

In Zerolang, use std.cli for hosted command-line flag and option helpers that sit one level above raw std.args access.

Runnable today:

API	Return	Notes
`std.cli.argEquals(index, expected)`	`Bool`	Checks one argument against an exact string.
`std.cli.command()`	`Maybe<String>`	Returns argument 1 as the command name.
`std.cli.commandOr(fallback)`	`String`	Returns the command name or a fallback.
`std.cli.commandEquals(expected)`	`Bool`	Checks argument 1 against an exact command string.
`std.cli.argOr(index, fallback)`	`String`	Returns an argument or a fallback.
`std.cli.argU32Or(index, fallback)`	`u32`	Parses an argument as `u32` or returns a fallback.
`std.cli.hasFlag(name)`	`Bool`	Reports whether an exact flag is present.
`std.cli.optionValue(name)`	`Maybe<String>`	Returns the value immediately after an option name.
`std.cli.optionValueOr(name, fallback)`	`String`	Returns the option value or a fallback.
`std.cli.optionU32(name)`	`Maybe<u32>`	Parses an option value as `u32`.
`std.cli.successExitCode()`	`i32`	Returns the conventional success exit code.
`std.cli.usageExitCode()`	`i32`	Returns the conventional command-line usage error code.
`std.cli.isHelp(command)`	`Bool`	Recognizes `help`, `--help`, and `-h`.
`std.cli.needsHelp()`	`Bool`	Reports whether the current invocation has no command or asks for help.
`std.cli.commandIn2(command, first, second)`	`Bool`	Checks a command against two accepted command names.
`std.cli.commandIn3(command, first, second, third)`	`Bool`	Checks a command against three accepted command names.
`std.cli.formatUsage(buffer, program, syntax)`	`Maybe<Span<u8>>`	Writes `usage: <program> <syntax>` into caller storage.
`std.cli.formatCommand(buffer, name, syntax, summary)`	`Maybe<Span<u8>>`	Writes one indented command help row.
`std.cli.formatOption(buffer, name, valueName, summary)`	`Maybe<Span<u8>>`	Writes one indented option help row.
`std.cli.formatSection(buffer, title)`	`Maybe<Span<u8>>`	Writes a section heading such as `Options:\n`.
`std.cli.formatHelpRow(buffer, label, summary)`	`Maybe<Span<u8>>`	Writes one padded, newline-terminated help row using the default label width.
`std.cli.formatHelpRowCustom(buffer, label, summary, indent, width)`	`Maybe<Span<u8>>`	Writes one padded help row using caller-supplied indentation and label width.
`std.cli.formatHelpRowWithWidth(buffer, label, summary, width)`	`Maybe<Span<u8>>`	Writes one padded help row using a caller-supplied label width.
`std.cli.formatHelp(buffer, usage, description)`	`Maybe<Span<u8>>`	Writes a help header with `Usage:` and an optional description.
`std.cli.formatError(buffer, message)`	`Maybe<Span<u8>>`	Writes an `error: ...` line.
`std.cli.formatUnknownCommand(buffer, command)`	`Maybe<Span<u8>>`	Writes a conventional unknown-command error.
`std.cli.formatMissingOperand(buffer, operand)`	`Maybe<Span<u8>>`	Writes a conventional missing-operand error.
`std.cli.formatInvalidOption(buffer, option)`	`Maybe<Span<u8>>`	Writes a conventional invalid-option error.

Current limits:

Table-driven command schemas.
Bool, signed integer, and usize option shortcuts; compose optionValue with std.parse.
Process exit from inside std.cli; use the returned exit-code constants with host process handling.

Example

pub fn main(world: World) -> Void raises {    if std.cli.needsHelp() {        var command_storage: [96]u8 = [0_u8; 96]        let commands: Maybe<Span<u8>> = std.cli.formatHelpRow(command_storage, "hello [name]", "print a greeting")        if commands.has {            var help_storage: [256]u8 = [0_u8; 256]            let help: Maybe<Span<u8>> = std.cli.formatHelp(help_storage, "zero-test [command]", "Small hosted CLI.")            if help.has {                check world.out.write(help.value)                check world.out.write("\nCommands:\n")                check world.out.write(commands.value)            }        }        return    }    let command: String = std.cli.commandOr("")    if std.mem.eql(command, "hello") {        let name: String = std.cli.argOr(2, "world")        check world.out.write("hello ")        check world.out.write(name)        check world.out.write("\n")        return    }    var error_storage: [64]u8 = [0_u8; 64]    let error: Maybe<Span<u8>> = std.cli.formatUnknownCommand(error_storage, command)    if error.has {        check world.err.write(error.value)        check world.err.write("\n")    }}

Design Notes

std.cli is a thin, hosted layer over std.args. It keeps subcommand, fallback, typed argument, help row, and usage error patterns regular without hiding process arguments behind a global parser or allocating command tables. For custom help layouts, compose formatHelp, formatSection, formatHelpRow, formatHelpRowWithWidth, and formatHelpRowCustom rather than relying on a global formatter state.