# 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
```sh
# From crates.io (requires Rust)
cargo install oag
# Or via the install script (Linux/macOS)
Windows users can download binaries from the [latest release](https://github.com/urmzd/oag/releases/latest).
## Commands
### `oag generate`
Generate code from an OpenAPI spec using the configuration in `oag.yaml`.
```sh
# Use config file (loads oag.yaml from current directory)
oag generate
# Override the input spec path
oag generate -i other-spec.yaml
```
**Flags:**
| `-i, --input <PATH>` | Path to the OpenAPI spec file (YAML or JSON). Overrides the `input` field in the config file. |
**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.
```sh
oag validate -i openapi.yaml
```
**Flags:**
| `-i, --input <PATH>` | **(required)** Path to the OpenAPI spec file to validate |
**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.
```sh
# YAML output (default)
oag inspect -i openapi.yaml
# JSON output
oag inspect -i openapi.yaml --format json
```
**Flags:**
| `-i, --input <PATH>` | **(required)** Path to the OpenAPI spec file |
| `--format <FORMAT>` | Output format: `yaml` (default) or `json` |
**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.
```sh
# Create config (fails if it already exists)
oag init
# Overwrite an existing config
oag init --force
```
**Flags:**
| `--force` | Overwrite an existing `oag.yaml` file |
### `oag completions`
Generate shell completion scripts for tab-completion of commands and flags.
```sh
# 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:**
| `<SHELL>` | **(required)** Target shell: `bash`, `zsh`, `fish`, `powershell`, `elvish` |
### `oag packs`
Manage packs for code generation.
```sh
# 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:**
| `list` | List available template packs (built-in + installed) |
| `install <SOURCE>` | Install a pack from a local directory |
| `install --builtin` | Extract all built-in packs to the templates directory |
| `remove <ID>` | Remove an installed template pack |
| `path` | Print the template packs directory path |
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](../../README.md#configuration) for the full configuration reference, including all generator options, layout modes, scaffold settings, and naming strategies.
## Environment variables
| `RUST_LOG` | Control log verbosity (e.g., `RUST_LOG=debug oag generate`). Uses [env_logger](https://docs.rs/env_logger/) syntax. |
## Exit codes
| `0` | Success |
| `1` | Error (invalid spec, missing config, I/O failure, generation error) |
## Depends on
- [`oag-core`](../oag-core/) — parser, IR, config, and template pack engine
- [`packs/`](../../packs/) — built-in template packs (embedded at compile time)
## Part of [oag](../../README.md)