fast-yaml-cli 0.4.0

# fy

[![Crates.io](https://img.shields.io/crates/v/fast-yaml-cli)](https://crates.io/crates/fast-yaml-cli)
[![CI](https://img.shields.io/github/actions/workflow/status/bug-ops/fast-yaml/ci.yml?branch=main)](https://github.com/bug-ops/fast-yaml/actions)
[![License](https://img.shields.io/crates/l/fast-yaml-cli)](LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.88.0-blue)](https://blog.rust-lang.org/)

Fast YAML command-line processor with validation and linting. Built on [fast-yaml](https://github.com/bug-ops/fast-yaml) for high-performance YAML 1.2.2 processing.

## Installation

### From crates.io

```bash
cargo install fast-yaml-cli
```

> [!TIP]
> Use `cargo binstall fast-yaml-cli` for faster installation without compilation.

### From source

```bash
git clone https://github.com/bug-ops/fast-yaml
cd fast-yaml
cargo install --path crates/fast-yaml-cli
```

### Verify installation

```bash
fy --version
fy --help
```

## Usage

```bash
fy [OPTIONS] [FILE] <COMMAND>
```

### Parse and validate

```bash
# Parse from file
fy parse config.yaml

# Parse from stdin
echo "name: test" | fy parse

# Show parse statistics
fy parse --stats large.yaml
```

### Format YAML

**Single file:**

```bash
# Format to stdout
fy format messy.yaml

# Custom indentation (2-8 spaces)
fy format --indent 4 --width 100 config.yaml

# Format in-place
fy format -i config.yaml
```

**Batch mode** (directories, globs, multiple files):

```bash
# Format entire directory (recursive)
fy format -i src/

# Format with glob pattern
fy format -i "configs/**/*.yaml"

# Multiple files
fy format -i file1.yaml file2.yaml file3.yaml

# Non-recursive directory formatting
fy format -i --no-recursive configs/

# Parallel processing with 8 workers
fy format -i -j 8 large-project/

# Read file paths from stdin
find . -name "*.yaml" | fy format -i --stdin-files
```

> [!TIP]
> Batch mode automatically detects when processing multiple files, directories, or glob patterns. Use `-j N` to control parallelism (default: auto-detect CPU cores).

**Include/exclude patterns:**

```bash
# Format all YAML except tests
fy format -i --exclude "**/tests/**" configs/

# Format only production configs
fy format -i --include "prod-*.yaml" configs/

# Combine patterns (respects .gitignore by default)
fy format -i --include "*.yaml" --exclude "draft-*" ./
```

**Dry run and output control:**

```bash
# Preview changes without modifying files
fy format -n configs/

# Quiet mode (only show errors)
fy format -i -q large-project/

# Verbose mode (show each file processed)
fy format -i -v configs/
```

### Convert formats

```bash
# YAML to JSON
fy convert json config.yaml > config.json

# JSON to YAML
fy convert yaml data.json > data.yaml

# Compact JSON (no pretty-print)
fy convert json --pretty=false app.yaml
```

### Lint YAML

```bash
# Lint with default rules
fy lint config.yaml

# Custom rules
fy lint --max-line-length 100 --indent-size 2 app.yaml

# JSON output for IDE integration
fy lint --format json config.yaml
```

## Commands

| Command | Description |
|---------|-------------|
| `parse` | Parse and validate YAML syntax |
| `format` | Format YAML with consistent style |
| `convert` | Convert between YAML and JSON |
| `lint` | Lint YAML with diagnostics |

## Options

### Common Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--in-place` | `-i` | Edit file in-place | - |
| `--output` | `-o` | Write to file | stdout |
| `--format` | `-f` | Output format (yaml/json/compact) | yaml |
| `--no-color` | - | Disable colored output | - |
| `--quiet` | `-q` | Suppress non-error output | - |
| `--verbose` | `-v` | Enable verbose output | - |

### Batch Mode Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--jobs` | `-j` | Number of parallel workers (0 = auto) | auto-detect |
| `--stdin-files` | - | Read file paths from stdin | - |
| `--include` | - | Include pattern (glob) | all files |
| `--exclude` | - | Exclude pattern (glob) | none |
| `--no-recursive` | - | Disable recursive directory traversal | recursive |
| `--dry-run` | `-n` | Preview changes without modifying | - |

> [!NOTE]
> Batch mode activates automatically when processing multiple paths, directories, glob patterns, or when using `--stdin-files`, `--include`, `--exclude`, or `--jobs`.

## Features

| Feature | Default | Description |
|---------|---------|-------------|
| `colors` | Yes | Colored terminal output |
| `linter` | Yes | YAML linting capabilities |
| `all` | - | All features enabled |

Build with minimal features:

```bash
cargo build --release --no-default-features
```

> [!NOTE]
> The `linter` feature adds the `lint` command. Without it, only `parse`, `format`, and `convert` are available.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Parse error |
| 2 | Lint errors found |
| 3 | I/O error |
| 4 | Invalid arguments |

## Examples

### Pipeline usage

```bash
# Validate all YAML files
find . -name "*.yaml" -exec fy parse {} \;

# Format and convert in one pipeline
cat config.yaml | fy format | fy convert json > config.json

# Check YAML before committing
git diff --name-only --cached -- '*.yaml' | xargs -I {} fy lint {}
```

### CI/CD integration

```yaml
# GitHub Actions
- name: Validate YAML
  run: |
    cargo install fast-yaml-cli
    find . -name "*.yaml" -exec fy lint {} \;
```

## Performance

Built on `fast-yaml-core` for optimal performance:

- **Startup time**: ~5ms
- **Binary size**: ~1MB (stripped)
- **Batch processing**: Multi-threaded with automatic CPU detection
- **Streaming**: Memory-mapped I/O for files >512KB
- **Full YAML 1.2.2 compliance**

> [!TIP]
> Batch mode provides 3-6x speedup on multi-core systems when processing 100+ files. Use `-j N` to control worker count.

## License

Licensed under [MIT](../../LICENSE-MIT) or [Apache-2.0](../../LICENSE-APACHE) at your option.