fauxdata-cli 0.1.3__tar.gz → 0.1.5__tar.gz

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "WebFetch(domain:posit-dev.github.io)",
       "WebFetch(domain:posit.co)",
       "mcp__chrome-devtools__navigate_page",
-      "mcp__chrome-devtools__lighthouse_audit"
+      "mcp__chrome-devtools__lighthouse_audit",
+      "WebFetch(domain:github.com)"
     ]
   }
 }

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/.gitignore

@@ -2,3 +2,4 @@ tmp/
 .venv/
 __pycache__/
 *.egg-info/
+.coverage

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/LOG.md

@@ -1,5 +1,23 @@
 # Log
 
+## 2026-06-12 — pointblank 0.25 + comando `infer`
+
+- Bump `pointblank>=0.25` (uscito su PyPI). Schemi inclusi (people/orders/events) verificati: tutti PASS.
+- Fase B regressioni: `rows_distinct` ora include righe con null (correttezza migliorata), lazy frame ok. fauxdata passa sempre DataFrame eager → nessun impatto.
+- Nuovo comando **`fauxdata infer DATASET`**: da tabella reale (csv/parquet/json/jsonl) genera schema YAML (`columns:` + `validation:`) via `pb.schema_from_tbl`. Flag: `--out/-o`, `--name/-n`, `--rows/-r`, `--format/-f`, `--categorical-threshold`, `--detect-presets/--no-detect-presets`, `--sample-size`.
+- `ColumnSchema`: nuovi campi `min_length`/`max_length` per stringhe (round-trip fedele); passati a `pb.string_field`. Validazione parsing (negativi, min>max).
+- infer CSV: `try_parse_dates=True` → date/datetime tipizzati invece che congelati come categorici.
+- generate: errore chiaro su conflitto unique+range stretto ("too narrow a range") invece del traceback criptico di pointblank.
+- Limite noto: colonne a bassa cardinalità congelate ai valori reali (possibile leak su colonne sensibili) — documentato nel README.
+- Test: +14 (`tests/test_infer.py` + length in `test_new_fields.py`). 102/102 pass, coverage 83.2%.
+
+- `init`: aggiunto `--description`, `--rows`, `--format`, `--yes`; questionary diventa fallback
+- Tutti i comandi: `epilog` con esempi in `--help`
+- `generate`: aggiunto `--dry-run` (mostra piano senza scrivere)
+- `generate`: output su successo mostra `output_path`, `format`, `rows` come chiave: valore
+- `init`: output su successo aggiunge `schema_path: <file>`
+- Fix venv: ricreato con `uv venv --clear` (cartella rinominata da `real_fake_datasets`)
+
 ## 2026-03-06 — v0.1.3
 
 - Add Python classifiers to pyproject.toml (3.11, 3.12, 3.13, MIT) — fixes pyversions badge

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fauxdata-cli
-Version: 0.1.3
+Version: 0.1.5
 Summary: CLI for generating and validating fake datasets
 Project-URL: Homepage, https://aborruso.github.io/fauxdata/
 Project-URL: Repository, https://github.com/aborruso/fauxdata
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
-Requires-Dist: pointblank>=0.22
+Requires-Dist: pointblank>=0.25
 Requires-Dist: polars>=1.0
 Requires-Dist: pyfiglet>=1.0
 Requires-Dist: pyyaml>=6.0
@@ -171,7 +171,7 @@ validation:
 |------|-------------|---------|
 | `int` | Integer | `min`, `max`, `unique` |
 | `float` | Floating point | `min`, `max` |
-| `string` | Text | `preset`, `values`, `unique` |
+| `string` | Text | `preset`, `values`, `pattern`, `unique`, `min_length`, `max_length` |
 | `bool` | Boolean | — |
 | `date` | Date | `min`, `max` (ISO format) |
 | `datetime` | Datetime | `min`, `max` (ISO format) |
@@ -259,6 +259,29 @@ fauxdata generate schemas/people.yml --out - --format jsonl | wc -l
 
 When `--out -` is used, all output messages are suppressed and only data is written to stdout.
 
+### `fauxdata infer DATASET`
+
+Build a YAML schema from a **real** dataset. fauxdata inspects the table (via pointblank's schema inference) and writes a schema with inferred ranges, categorical value sets, string presets (email, url…), uniqueness, null rates, and string lengths — plus matching `validation:` rules. Feed the result back to `fauxdata generate` to produce synthetic data that mirrors the real shape, without ever shipping the real values.
+
+```
+fauxdata infer real_data.csv                                   # -> real_data.yml
+fauxdata infer real_data.parquet --out schema.yml --name people
+fauxdata infer real_data.csv --categorical-threshold 50 --no-detect-presets
+fauxdata infer big.parquet --sample-size 10000 --out - | head  # stream to stdout
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--out` | `-o` | `<name>.yml` | Output YAML path — use `-` for stdout |
+| `--name` | `-n` | dataset stem | Schema name |
+| `--rows` | `-r` | source rows | Rows to generate (written into the schema) |
+| `--format` | `-f` | `csv` | Default output format written into the schema |
+| `--categorical-threshold` | | `20` | Max unique values (int) or fraction (`0`–`1`) to treat a column as categorical |
+| `--detect-presets` / `--no-detect-presets` | | on | Match string columns to known presets (email, url…) |
+| `--sample-size` | | all rows | Sample N rows before analysis (for very large tables) |
+
+> **Notes.** Low-cardinality columns (≤ `--categorical-threshold` distinct values) are frozen to their exact source values via `values:` — desirable for categories like `status`, but it means sensitive low-cardinality columns are reproduced verbatim. Raise the threshold or edit the schema if that's not what you want. Also, a column inferred as `unique` over a narrow integer range cannot generate many more rows than the source; widen `min`/`max` or drop `unique` to amplify.
+
 ### `fauxdata validate DATASET SCHEMA`
 
 ```

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/README.md

@@ -147,7 +147,7 @@ validation:
 |------|-------------|---------|
 | `int` | Integer | `min`, `max`, `unique` |
 | `float` | Floating point | `min`, `max` |
-| `string` | Text | `preset`, `values`, `unique` |
+| `string` | Text | `preset`, `values`, `pattern`, `unique`, `min_length`, `max_length` |
 | `bool` | Boolean | — |
 | `date` | Date | `min`, `max` (ISO format) |
 | `datetime` | Datetime | `min`, `max` (ISO format) |
@@ -235,6 +235,29 @@ fauxdata generate schemas/people.yml --out - --format jsonl | wc -l
 
 When `--out -` is used, all output messages are suppressed and only data is written to stdout.
 
+### `fauxdata infer DATASET`
+
+Build a YAML schema from a **real** dataset. fauxdata inspects the table (via pointblank's schema inference) and writes a schema with inferred ranges, categorical value sets, string presets (email, url…), uniqueness, null rates, and string lengths — plus matching `validation:` rules. Feed the result back to `fauxdata generate` to produce synthetic data that mirrors the real shape, without ever shipping the real values.
+
+```
+fauxdata infer real_data.csv                                   # -> real_data.yml
+fauxdata infer real_data.parquet --out schema.yml --name people
+fauxdata infer real_data.csv --categorical-threshold 50 --no-detect-presets
+fauxdata infer big.parquet --sample-size 10000 --out - | head  # stream to stdout
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--out` | `-o` | `<name>.yml` | Output YAML path — use `-` for stdout |
+| `--name` | `-n` | dataset stem | Schema name |
+| `--rows` | `-r` | source rows | Rows to generate (written into the schema) |
+| `--format` | `-f` | `csv` | Default output format written into the schema |
+| `--categorical-threshold` | | `20` | Max unique values (int) or fraction (`0`–`1`) to treat a column as categorical |
+| `--detect-presets` / `--no-detect-presets` | | on | Match string columns to known presets (email, url…) |
+| `--sample-size` | | all rows | Sample N rows before analysis (for very large tables) |
+
+> **Notes.** Low-cardinality columns (≤ `--categorical-threshold` distinct values) are frozen to their exact source values via `values:` — desirable for categories like `status`, but it means sensitive low-cardinality columns are reproduced verbatim. Raise the threshold or edit the schema if that's not what you want. Also, a column inferred as `unique` over a narrow integer range cannot generate many more rows than the source; widen `min`/`max` or drop `unique` to amplify.
+
 ### `fauxdata validate DATASET SCHEMA`
 
 ```

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fauxdata-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "CLI for generating and validating fake datasets"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,7 +13,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "pointblank>=0.22",
+    "pointblank>=0.25",
     "typer>=0.12",
     "rich>=13",
     "pyfiglet>=1.0",

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/src/fauxdata/__init__.py

@@ -1,3 +1,3 @@
 """fauxdata - CLI for generating and validating fake datasets."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/src/fauxdata/commands/generate.py

@@ -19,6 +19,15 @@ from fauxdata.validator import validate_dataset
 console = Console()
 
 
+def _generate(schema, n, rng_seed):
+    """Generate, translating generation errors into a clean CLI exit."""
+    try:
+        return generate_dataset(schema, rows=n, seed=rng_seed)
+    except ValueError as e:
+        rprint(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+
 def run(
     schema_path: str,
     rows: Optional[int] = None,
@@ -26,6 +35,7 @@ def run(
     fmt: Optional[str] = None,
     seed: Optional[int] = None,
     validate: bool = False,
+    dry_run: bool = False,
 ):
     """Generate a fake dataset from a YAML schema."""
     schema = load_schema(schema_path)
@@ -37,21 +47,35 @@ def run(
 
     stdout_mode = output_path == "-"
 
+    if dry_run:
+        rprint(Panel(f"[bold cyan]fauxdata generate --dry-run[/bold cyan]  [dim]{schema_path}[/dim]", expand=False))
+        rprint("[yellow]Dry run — no files will be written.[/yellow]\n")
+        rprint(f"  schema:      {schema_path}")
+        rprint(f"  rows:        {n}")
+        rprint(f"  seed:        {rng_seed}")
+        rprint(f"  format:      {output_fmt}")
+        rprint(f"  output_path: {output_path}")
+        rprint(f"  validate:    {validate}")
+        rprint(f"  columns:     {', '.join(c.name for c in schema.columns)}")
+        return
+
     if not stdout_mode:
         rprint(Panel(f"[bold cyan]fauxdata generate[/bold cyan]  [dim]{schema_path}[/dim]", expand=False))
 
     if stdout_mode:
-        df = generate_dataset(schema, rows=n, seed=rng_seed)
+        df = _generate(schema, n, rng_seed)
         write_stdout(df, output_fmt)
         return
 
     with console.status(f"[bold green]Generating {n} rows...[/bold green]"):
-        df = generate_dataset(schema, rows=n, seed=rng_seed)
+        df = _generate(schema, n, rng_seed)
 
     _print_schema_table(schema, n, rng_seed)
 
     saved = export_dataset(df, output_path, output_fmt)
-    rprint(f"\n[green]Saved[/green] [bold]{saved}[/bold]  ([dim]{output_fmt}, {n} rows[/dim])")
+    rprint(f"\noutput_path: {saved}")
+    rprint(f"format: {output_fmt}")
+    rprint(f"rows: {n}")
 
     if validate:
         _run_validation(df, schema)

fauxdata_cli-0.1.5/src/fauxdata/commands/infer.py

@@ -0,0 +1,178 @@
+"""fauxdata infer command - build a YAML schema from a real dataset.
+
+Uses pointblank's ``schema_from_tbl`` (>=0.25) to infer rich constraints
+(min/max, unique, null rate, allowed values, presets, string lengths) from an
+existing table, then serializes them into a fauxdata YAML schema that can be
+fed back to ``fauxdata generate``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pointblank as pb
+import polars as pl
+import typer
+import yaml
+from rich import print as rprint
+from rich.panel import Panel
+
+# Polars dtype name (str) -> fauxdata col_type
+_DTYPE_MAP = {
+    "Int": "int",
+    "UInt": "int",
+    "Float": "float",
+    "String": "string",
+    "Utf8": "string",
+    "Boolean": "bool",
+    "Datetime": "datetime",
+    "Date": "date",
+}
+
+
+def _col_type_from_dtype(dtype: str) -> str:
+    """Map a pointblank/polars dtype name to a fauxdata col_type."""
+    for prefix, ctype in _DTYPE_MAP.items():
+        if dtype.startswith(prefix):
+            return ctype
+    return "string"
+
+
+def _field_to_spec(field) -> dict:
+    """Convert an inferred pointblank Field into a fauxdata column spec dict."""
+    attrs = vars(field)
+    col_type = _col_type_from_dtype(attrs.get("dtype", "String"))
+    spec: dict = {"type": col_type}
+
+    if attrs.get("unique"):
+        spec["unique"] = True
+    if attrs.get("nullable"):
+        spec["nullable"] = True
+    np = attrs.get("null_probability")
+    if np:
+        spec["null_probability"] = round(float(np), 4)
+
+    if col_type in ("int", "float"):
+        if attrs.get("min_val") is not None:
+            spec["min"] = attrs["min_val"]
+        if attrs.get("max_val") is not None:
+            spec["max"] = attrs["max_val"]
+        if attrs.get("allowed"):
+            spec["values"] = list(attrs["allowed"])
+
+    elif col_type in ("date", "datetime"):
+        if attrs.get("min_date") is not None:
+            spec["min"] = str(attrs["min_date"])
+        if attrs.get("max_date") is not None:
+            spec["max"] = str(attrs["max_date"])
+
+    elif col_type == "string":
+        if attrs.get("preset"):
+            spec["preset"] = attrs["preset"]
+        elif attrs.get("allowed"):
+            spec["values"] = list(attrs["allowed"])
+        elif attrs.get("pattern"):
+            spec["pattern"] = attrs["pattern"]
+        if attrs.get("min_length") is not None:
+            spec["min_length"] = attrs["min_length"]
+        if attrs.get("max_length") is not None:
+            spec["max_length"] = attrs["max_length"]
+
+    return spec
+
+
+def _build_validation(columns: list[tuple[str, dict]]) -> list[dict]:
+    """Derive validation rules from the inferred column specs."""
+    rules: list[dict] = []
+
+    not_null = [name for name, spec in columns if not spec.get("nullable")]
+    if not_null:
+        rules.append({"rule": "col_vals_not_null", "columns": not_null})
+
+    for name, spec in columns:
+        if spec["type"] in ("int", "float") and "min" in spec and "max" in spec:
+            rules.append({"rule": "col_vals_between", "column": name,
+                          "min": spec["min"], "max": spec["max"]})
+
+    for name, spec in columns:
+        if "values" in spec:
+            rules.append({"rule": "col_vals_in_set", "column": name, "values": list(spec["values"])})
+
+    unique_cols = [name for name, spec in columns if spec.get("unique")]
+    if unique_cols:
+        rules.append({"rule": "rows_distinct", "columns": unique_cols})
+
+    return rules
+
+
+def _load_table(path: str) -> pl.DataFrame:
+    ext = path.rsplit(".", 1)[-1].lower()
+    if ext == "csv":
+        # try_parse_dates so date/datetime columns are typed (not frozen as categorical strings)
+        return pl.read_csv(path, try_parse_dates=True)
+    if ext == "parquet":
+        return pl.read_parquet(path)
+    if ext == "json":
+        return pl.read_json(path)
+    if ext in ("jsonl", "ndjson"):
+        return pl.read_ndjson(path)
+    rprint(f"[red]Unsupported file format: .{ext}[/red]")
+    raise typer.Exit(code=1)
+
+
+def run(
+    dataset_path: str,
+    out: str | None = None,
+    name: str | None = None,
+    rows: int | None = None,
+    fmt: str = "csv",
+    categorical_threshold: float = 20,
+    detect_presets: bool = True,
+    sample_size: int | None = None,
+):
+    """Infer a fauxdata YAML schema from a real dataset."""
+    rprint(Panel(
+        f"[bold cyan]fauxdata infer[/bold cyan]  [dim]{dataset_path}[/dim]",
+        expand=False,
+    ))
+
+    df = _load_table(dataset_path)
+    rprint(f"  Loaded [bold]{len(df)}[/bold] rows, [bold]{len(df.columns)}[/bold] columns")
+
+    pb_schema = pb.schema_from_tbl(
+        df,
+        categorical_threshold=categorical_threshold,
+        detect_presets=detect_presets,
+        sample_size=sample_size,
+    )
+
+    columns = [(col_name, _field_to_spec(field)) for col_name, field in pb_schema.columns]
+
+    schema_name = name or Path(dataset_path).stem
+    out_rows = rows if rows is not None else len(df)
+
+    schema_dict = {
+        "name": schema_name,
+        "description": f"Inferred from {Path(dataset_path).name}",
+        "rows": out_rows,
+        "seed": 42,
+        "output": {"format": fmt, "path": f"{schema_name}.{fmt}"},
+        "columns": {col_name: spec for col_name, spec in columns},
+        "validation": _build_validation(columns),
+    }
+
+    text = yaml.safe_dump(schema_dict, sort_keys=False, allow_unicode=True, default_flow_style=False)
+
+    out_path = out or f"{schema_name}.yml"
+    if out_path == "-":
+        import sys
+        sys.stdout.write(text)
+        return
+
+    Path(out_path).write_text(text)
+    rprint(f"[green]Created[/green] [bold]{out_path}[/bold] "
+           f"([bold]{len(columns)}[/bold] columns, "
+           f"[bold]{len(schema_dict['validation'])}[/bold] validation rules)")
+    rprint("[dim]Generate synthetic data with:[/dim]")
+    rprint(f"  [cyan]fauxdata generate {out_path} --validate[/cyan]")
+    rprint(f"schema_path: {out_path}")

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/src/fauxdata/commands/init.py

@@ -75,8 +75,14 @@ validation:
 """
 
 
-def run(name: str | None = None):
-    """Interactive schema template creator."""
+def run(
+    name: str | None = None,
+    description: str | None = None,
+    rows: str | None = None,
+    fmt: str | None = None,
+    yes: bool = False,
+):
+    """Create a schema template."""
     rprint(Panel("[bold cyan]fauxdata init[/bold cyan] — schema template creator", expand=False))
 
     schema_name = name or questionary.text(
@@ -87,30 +93,37 @@ def run(name: str | None = None):
     if schema_name is None:
         raise typer.Abort()
 
-    description = questionary.text(
-        "Short description:",
-        default=f"{schema_name} dataset",
-    ).ask() or ""
+    desc = description if description is not None else (
+        questionary.text(
+            "Short description:",
+            default=f"{schema_name} dataset",
+        ).ask() or ""
+    )
 
-    rows = questionary.text("Default number of rows:", default="1000").ask() or "1000"
+    n_rows = rows if rows is not None else (
+        questionary.text("Default number of rows:", default="1000").ask() or "1000"
+    )
 
-    fmt = questionary.select(
-        "Default output format:",
-        choices=["csv", "parquet", "json", "jsonl"],
-    ).ask() or "csv"
+    output_fmt = fmt if fmt is not None else (
+        questionary.select(
+            "Default output format:",
+            choices=["csv", "parquet", "json", "jsonl"],
+        ).ask() or "csv"
+    )
 
     output_file = f"{schema_name}.yml"
     out_path = Path(output_file)
 
-    if out_path.exists():
+    if out_path.exists() and not yes:
         overwrite = questionary.confirm(f"{output_file} already exists. Overwrite?", default=False).ask()
         if not overwrite:
             rprint("[yellow]Aborted.[/yellow]")
             raise typer.Exit()
 
-    content = TEMPLATE.format(name=schema_name, description=description, rows=rows, fmt=fmt)
+    content = TEMPLATE.format(name=schema_name, description=desc, rows=n_rows, fmt=output_fmt)
     out_path.write_text(content)
 
     rprint(f"[green]Created[/green] [bold]{output_file}[/bold]")
     rprint("[dim]Edit the schema then run:[/dim]")
     rprint(f"  [cyan]fauxdata generate {output_file} --validate[/cyan]")
+    rprint(f"schema_path: {output_file}")

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.5}/src/fauxdata/generator.py

@@ -16,7 +16,17 @@ def generate_dataset(schema: SchemaConfig, rows: int | None = None, seed: int |
     pb_schema = _build_pb_schema(schema)
     country = schema.locale or "US"
 
-    df = pb.generate_dataset(pb_schema, n=n, seed=rng_seed, country=country)
+    try:
+        df = pb.generate_dataset(pb_schema, n=n, seed=rng_seed, country=country)
+    except ValueError as e:
+        if "unique values" in str(e):
+            unique_cols = [c.name for c in schema.columns if c.unique]
+            raise ValueError(
+                f"Cannot generate {n} rows: a unique column has too narrow a range "
+                f"(unique columns: {', '.join(unique_cols) or 'n/a'}). "
+                f"Reduce --rows, widen min/max, or drop 'unique'."
+            ) from e
+        raise
     return df
 
 
@@ -82,7 +92,12 @@ def _col_to_field(col: ColumnSchema):
         elif col.preset:
             return pb.string_field(preset=col.preset, nullable=nullable, unique=unique, **np_kwargs)
         else:
-            return pb.string_field(nullable=nullable, unique=unique, **np_kwargs)
+            len_kwargs = {}
+            if col.min_length is not None:
+                len_kwargs["min_length"] = col.min_length
+            if col.max_length is not None:
+                len_kwargs["max_length"] = col.max_length
+            return pb.string_field(nullable=nullable, unique=unique, **len_kwargs, **np_kwargs)
 
     else:
         return pb.string_field(nullable=nullable, **np_kwargs)

fauxdata_cli-0.1.5/src/fauxdata/main.py

@@ -0,0 +1,153 @@
+"""fauxdata CLI entry point."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pyfiglet
+import typer
+from rich import print as rprint
+from rich.console import Console
+
+from fauxdata import __version__
+
+app = typer.Typer(
+    name="fauxdata",
+    help="Generate and validate fake datasets from YAML schemas.",
+    add_completion=False,
+)
+console = Console()
+
+
+def _banner():
+    banner = pyfiglet.figlet_format("fauxdata", font="slant")
+    rprint(f"[bold cyan]{banner}[/bold cyan]")
+    rprint("[dim]Generate and validate realistic fake datasets[/dim]\n")
+
+
+def _version_callback(value: bool):
+    if value:
+        rprint(f"fauxdata {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-V", callback=_version_callback, is_eager=True,
+        help="Show version and exit.",
+    ),
+):
+    if ctx.invoked_subcommand is None:
+        _banner()
+        rprint(ctx.get_help())
+
+
+@app.command(
+    "init",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata init --name people\n\n"
+        "  fauxdata init --name orders --rows 500 --format parquet\n\n"
+        "  fauxdata init --name events --description 'clickstream events' --rows 10000 --format jsonl --yes\n"
+    ),
+)
+def init_cmd(
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Schema name"),
+    description: Optional[str] = typer.Option(None, "--description", "-d", help="Short description"),
+    rows: Optional[str] = typer.Option(None, "--rows", "-r", help="Default number of rows (default: 1000)"),
+    fmt: Optional[str] = typer.Option(None, "--format", "-f", help="Output format: csv, parquet, json, jsonl (default: csv)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Overwrite existing file without confirmation"),
+):
+    """Create a schema template (interactive if flags are omitted)."""
+    from fauxdata.commands.init import run
+    run(name=name, description=description, rows=rows, fmt=fmt, yes=yes)
+
+
+@app.command(
+    "infer",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata infer real_data.csv\n\n"
+        "  fauxdata infer real_data.parquet --out schema.yml --name people\n\n"
+        "  fauxdata infer real_data.csv --categorical-threshold 50 --no-detect-presets\n\n"
+        "  fauxdata infer big.parquet --sample-size 10000 --out - | head\n"
+    ),
+)
+def infer_cmd(
+    dataset: str = typer.Argument(..., help="Path to a real dataset (csv, parquet, json, jsonl)"),
+    out: Optional[str] = typer.Option(None, "--out", "-o", help="Output YAML path (use - for stdout; default: <name>.yml)"),
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Schema name (default: dataset file stem)"),
+    rows: Optional[int] = typer.Option(None, "--rows", "-r", help="Rows to generate (default: rows in source table)"),
+    fmt: str = typer.Option("csv", "--format", "-f", help="Default output format in the schema: csv, parquet, json, jsonl"),
+    categorical_threshold: float = typer.Option(20, "--categorical-threshold", help="Max unique values (int) or fraction (0-1) to treat a column as categorical"),
+    detect_presets: bool = typer.Option(True, "--detect-presets/--no-detect-presets", help="Match string columns to known presets (email, url, ...)"),
+    sample_size: Optional[int] = typer.Option(None, "--sample-size", help="Sample N rows before analysis (for very large tables)"),
+):
+    """Infer a YAML schema from a real dataset (powered by pointblank schema inference)."""
+    from fauxdata.commands.infer import run
+    run(
+        dataset_path=dataset, out=out, name=name, rows=rows, fmt=fmt,
+        categorical_threshold=categorical_threshold, detect_presets=detect_presets,
+        sample_size=sample_size,
+    )
+
+
+@app.command(
+    "generate",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata generate people.yml\n\n"
+        "  fauxdata generate people.yml --rows 500 --format csv --out out.csv\n\n"
+        "  fauxdata generate people.yml --seed 42 --validate\n\n"
+        "  fauxdata generate people.yml --out - --format jsonl | jq .\n\n"
+        "  fauxdata generate people.yml --dry-run\n"
+    ),
+)
+def generate_cmd(
+    schema: str = typer.Argument(..., help="Path to YAML schema file"),
+    rows: Optional[int] = typer.Option(None, "--rows", "-r", help="Number of rows to generate"),
+    out: Optional[str] = typer.Option(None, "--out", "-o", help="Output file path (use - for stdout)"),
+    fmt: Optional[str] = typer.Option(None, "--format", "-f", help="Output format: csv, parquet, json, jsonl"),
+    seed: Optional[int] = typer.Option(None, "--seed", "-s", help="Random seed for reproducibility"),
+    validate: bool = typer.Option(False, "--validate", "-v", help="Run validation after generating"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be generated without writing files"),
+):
+    """Generate a fake dataset from a YAML schema."""
+    from fauxdata.commands.generate import run
+    run(schema_path=schema, rows=rows, out=out, fmt=fmt, seed=seed, validate=validate, dry_run=dry_run)
+
+
+@app.command(
+    "validate",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata validate people.csv people.yml\n\n"
+        "  fauxdata validate out/orders.parquet schemas/orders.yml\n"
+    ),
+)
+def validate_cmd(
+    dataset: str = typer.Argument(..., help="Path to dataset file (csv, parquet, json, jsonl)"),
+    schema: str = typer.Argument(..., help="Path to YAML schema file"),
+):
+    """Validate an existing dataset against a YAML schema."""
+    from fauxdata.commands.validate import run
+    run(dataset_path=dataset, schema_path=schema)
+
+
+@app.command(
+    "preview",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata preview people.csv\n\n"
+        "  fauxdata preview people.parquet --rows 20\n"
+    ),
+)
+def preview_cmd(
+    dataset: str = typer.Argument(..., help="Path to dataset file"),
+    rows: int = typer.Option(10, "--rows", "-r", help="Number of rows to preview"),
+):
+    """Show a preview and column statistics for a dataset."""
+    from fauxdata.commands.preview import run
+    run(dataset_path=dataset, rows=rows)