vercel-labs--zerolang/docs/articles/modules/cli.md

## 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

```zero
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.