# @hulla/args

> Parse flags, positionals, and nested commands into typed values, with Zod validation and access to the raw input.

`@hulla/args` turns command-line input into typed values. Declare the options and commands your CLI accepts, then parse the arguments with Zod validation.

Your code decides what to do with the result, including printing help and reporting errors.

**Interactive example: **Type a bad port, omit it, or add a flag. Real parsing distinguishes invalid input from absence before your handler runs.

The browser runs @hulla/args and Zod on whitespace-separated tokens. Invalid input and omitted options remain distinct. No shell command or preview server runs.

```ts
import { parser, option } from '@hulla/args'
import { z } from 'zod'

const cli = parser({
  name: 'preview',
  arguments: [
    option({ name: 'port', schema: z.coerce.number().int().min(1).max(65535) }),
  ],
})
const port = cli.parse(['--port', '8080']).arguments.port
port.value // number: 8080
port.detected // true
```

[Build the working example](https://hulla.dev/guides/args/quick-start.md)

## Choose a guide

- [Quick start](https://hulla.dev/guides/args/quick-start.md) — Build and run a small greeting command.
- [Arguments](https://hulla.dev/docs/args/arguments.md) — Flags, options, positionals, and sequences.
- [Commands](https://hulla.dev/docs/args/commands.md) — Aliases and nested commands.
- [Validation](https://hulla.dev/docs/args/validation.md) — Validate provided values with Zod schemas.
- [Parser options](https://hulla.dev/docs/args/options.md) — Configure argv slicing and parsing behavior.
- [Build a notes CLI](https://hulla.dev/guides/args/recipes.md) — Save and list notes with validation and error handling.
- [Reference](https://hulla.dev/docs/args/reference.md) — Constructors, result fields, and error metadata.