CLI Reference

Complete reference for the Vague command-line interface.

Basic Usage

vague <file.vague> [options]

Output Options

Control where and how Vague writes generated data:

Option	Description
-o, --output <file>	Write output to file
-f, --format <fmt>	Output format: json (default), csv, ndjson
-p, --pretty	Pretty-print JSON output

# Output to file
vague data.vague -o output.json

# Pretty print
vague data.vague -p

# CSV format
vague data.vague -f csv -o data.csv

# NDJSON format (newline-delimited JSON)
vague data.vague -f ndjson -o data.ndjson

Reproducibility

Generate consistent output across runs:

Option	Description
-s, --seed <number>	Seed for reproducible generation
-w, --watch	Watch input file and regenerate on changes (requires -o)

# Reproducible output
vague data.vague --seed 42

# Watch mode
vague data.vague -o output.json -w

CSV Options

Configure CSV output formatting:

Option	Description
--csv-delimiter <char>	Field delimiter (default: ,)
--csv-no-header	Omit header row
--csv-arrays <mode>	Array handling: json, first, count
--csv-nested <mode>	Nested objects: flatten, json

# Semicolon delimiter
vague data.vague -f csv --csv-delimiter ";"

# No header row
vague data.vague -f csv --csv-no-header

OpenAPI Validation

Validate generated data against an OpenAPI specification:

Option	Description
-v, --validate <spec>	Validate against OpenAPI spec
-m, --mapping <json>	Schema mapping {"collection": "Schema"}
--validate-only	Only validate, don't output data

# Validate generated data
vague data.vague -v openapi.json -m '{"invoices": "Invoice"}'

# Validate only (for CI)
vague data.vague -v openapi.json --validate-only

OpenAPI Example Population

Populate OpenAPI specs with generated examples:

Option	Description
--oas-source <spec>	Source OpenAPI spec to populate
--oas-output <file>	Output path for populated spec
--oas-example-count <n>	Examples per schema (default: 1)
--oas-external	Use external file references

# Populate spec with examples
vague data.vague --oas-source api.json --oas-output api.json

# Multiple examples
vague data.vague --oas-source api.json --oas-output api.json --oas-example-count 3

OpenAPI Linting

Lint OpenAPI specs using Spectral:

Option	Description
--lint-spec <file>	Lint OpenAPI spec with Spectral
--lint-verbose	Show detailed lint results

# Lint spec
vague --lint-spec openapi.json

# Verbose output
vague --lint-spec openapi.yaml --lint-verbose

Schema Inference

Reverse-engineer Vague schemas from existing data:

Option	Description
--infer <file>	Infer schema from JSON/CSV
--collection-name <name>	Collection name for CSV
--dataset-name <name>	Dataset name for inference (default: Generated)
--infer-delimiter <char>	CSV delimiter (default: ,)
--no-formats	Disable format detection (uuid, email, etc.)
--no-weights	Disable weighted superpositions
--max-enum <n>	Max unique values for enum detection (default: 10)

# Infer from JSON
vague --infer data.json -o schema.vague

# Infer from CSV
vague --infer data.csv --collection-name employees

Data Validation

Validate external JSON data against Vague schema constraints:

Option	Description
--validate-data <file>	Validate JSON against Vague schema (requires --schema)
--schema <file>	Schema file for data validation
--dataset <name>	Dataset name for validate {} block constraints

# Validate external data
vague --validate-data data.json --schema schema.vague

TypeScript Generation

Generate TypeScript type definitions from schemas:

Option	Description
--typescript	Generate TypeScript definitions (inference mode only)
--ts-only	Only TypeScript (no .vague, inference mode only)

# Generate TypeScript
vague --infer data.json --typescript

# TypeScript only
vague --infer data.json --ts-only

Plugins

Load custom generator plugins:

Option	Description
--plugins <dir>	Load plugins from directory
--no-auto-plugins	Disable automatic plugin discovery

# Load custom plugins
vague data.vague --plugins ./custom-plugins

# Disable auto-discovery
vague data.vague --no-auto-plugins --plugins ./plugins

Mock Server

Serve generated data over HTTP instead of writing files:

Option	Description
--serve [port]	Start HTTP mock server (default port: 3000)

vague data.vague --serve          # http://localhost:3000
vague data.vague --serve 8080    # Custom port

Each collection becomes an endpoint (GET /invoices, GET /invoices/:index).

Enterprise Reporting

Generate audit trails and reports for compliance:

Option	Description
--report <file>	Generate report (.html and .md detected by extension; anything else gets JSON)
--report-format <fmt>	Report format override: json, html, markdown
--audit-log <file>	Append audit log entry to JSONL file
--baseline <file>	Compare against baseline report for distribution drift (requires --report)

vague data.vague -o data.json --report report.html
vague data.vague --audit-log audit.jsonl
vague data.vague --report new.json --baseline old.json

Debugging

Enable detailed logging for troubleshooting:

Option	Description
-d, --debug	Enable debug logging
--log-level <level>	Set log level: none, error, warn, info, debug
--verbose	Show verbose output

# Debug mode
vague data.vague --debug

# Verbose output
vague data.vague --verbose

Environment variable:

VAGUE_DEBUG=generator,constraint vague data.vague

Debug components: lexer, parser, generator, constraint, validator, plugin, cli, openapi, infer, config

Help

vague --help
vague -h

Examples

Development Workflow

# Generate and watch
vague fixtures.vague -o fixtures.json -w -p

# Generate with validation
vague data.vague -v api.json -o output.json -p

CI/CD Pipeline

# Validate and fail on error
vague data.vague -v openapi.json --validate-only

# Lint API spec
vague --lint-spec api.yaml

Data Migration

# Infer schema from existing data
vague --infer legacy-data.json -o schema.vague

# Generate new data matching schema
vague schema.vague -o new-data.json -s 42

API Documentation

# Populate OpenAPI with examples
vague examples.vague \
  --oas-source api.yaml \
  --oas-output api-documented.yaml \
  --oas-example-count 2

Configuration File

Create vague.config.js for default options:

Option	Description
-c, --config <file>	Use specific config file (default: auto-detect vague.config.js)
--no-config	Skip loading config file

// vague.config.js
export default {
  plugins: ['./plugins/custom.js'],
  seed: 42,
  pretty: true
};

Exit Codes

Code	Meaning
0	Success
1	Validation, generation, or argument error