oag-cli

Command-line interface for oag — an OpenAPI 3.x code generator.

Installs a single binary called oag that parses OpenAPI specs and generates typed clients and servers.

Install

# From crates.io (requires Rust)
cargo install oag

# Or via the install script (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/urmzd/oag/main/install.sh | sh

Windows users can download binaries from the latest release.

Commands

oag generate

Generate code from an OpenAPI spec using the configuration in oag.yaml.

# Use config file (loads oag.yaml from current directory)
oag generate

# Override the input spec path
oag generate -i other-spec.yaml

Flags:

Behavior:

1. Loads oag.yaml from the current directory (falls back to defaults if missing)
2. Parses the OpenAPI spec and transforms it into an intermediate representation (IR)
3. For each generator in the generators map, generates code into the specified output directory
4. Writes a README.md in each output directory warning against manual edits
5. Auto-runs formatters if their config files are detected (e.g., biome.json, ruff.toml)

oag validate

Validate an OpenAPI spec and report its contents without generating any code.

oag validate -i openapi.yaml

Flags:

Output: Reports the spec version, title, number of paths, schemas, operations, and IR schemas. Exits with a non-zero code if the spec is invalid.

oag inspect

Dump the parsed intermediate representation (IR) so you can see exactly what oag understands from your spec. Useful for debugging or understanding how your spec maps to generated code.

# YAML output (default)
oag inspect -i openapi.yaml

# JSON output
oag inspect -i openapi.yaml --format json

Flags:

Output: A structured summary containing:

• info — spec title and version
• schemas — all resolved schemas with their name and kind (object, enum, alias, union)
• operations — all operations with name, method, path, return kind (standard, sse, void), and tags
• modules — operation groups (by tag)

oag init

Create a oag.yaml configuration file in the current directory with sensible defaults and commented-out examples for all generators.

# Create config (fails if it already exists)
oag init

# Overwrite an existing config
oag init --force

Flags:

oag completions

Generate shell completion scripts for tab-completion of commands and flags.

# Bash
oag completions bash >> ~/.bashrc

# Zsh
oag completions zsh >> ~/.zshrc

# Fish
oag completions fish > ~/.config/fish/completions/oag.fish

# PowerShell
oag completions powershell >> $PROFILE

Arguments:

oag packs

Manage packs for code generation.

# List available packs (built-in + installed)
oag packs list

# Extract all built-in packs to the packs directory for customization
oag packs install --builtin

# Install a custom pack from a local directory
oag packs install /path/to/my-pack

# Remove an installed pack
oag packs remove my-pack

Subcommands:

Installed packs take precedence over built-in packs, allowing you to customize any built-in pack by extracting and modifying it.

Configuration

The CLI automatically loads oag.yaml from the current directory. Run oag init to create one with defaults.

See the root README for the full configuration reference, including all generator options, layout modes, scaffold settings, and naming strategies.

Environment variables

Exit codes

Depends on

• oag-core — parser, IR, config, and template pack engine
• packs/ — built-in template packs (embedded at compile time)

Part of oag