> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pidgeon.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Flock Commands

> CLI commands for Flock synthetic population generation — connect to databases, learn patterns, generate populations, and seed data.

## pidgeon flock connect

Connect to a database and analyze its schema.

```bash theme={null}
pidgeon flock connect --provider <type> --connection-string <str>
```

| Flag                        | Type   | Description                                     |
| --------------------------- | ------ | ----------------------------------------------- |
| `--provider <type>`         | string | Database type: `postgres`, `mysql`, `sqlserver` |
| `--connection-string <str>` | string | Database connection string                      |

```bash theme={null}
pidgeon flock connect \
  --provider postgres \
  --connection-string "Host=localhost;Port=5432;Database=ehr;Username=dev;Password=${DB_PASSWORD}"
```

***

## pidgeon flock learn

Learn statistical patterns from existing sample data.

```bash theme={null}
pidgeon flock learn [options]
```

| Flag                | Type   | Default    | Description                               |
| ------------------- | ------ | ---------- | ----------------------------------------- |
| `--tables <list>`   | string | All tables | Comma-separated list of tables to analyze |
| `--sample-size <n>` | int    | `100`      | Number of rows to sample per table        |

```bash theme={null}
pidgeon flock learn --tables patients,encounters,diagnoses --sample-size 500
```

***

## pidgeon flock generate

Generate a synthetic patient population.

```bash theme={null}
pidgeon flock generate [options]
```

| Flag                          | Type   | Default | Description                                |
| ----------------------------- | ------ | ------- | ------------------------------------------ |
| `--count <n>`                 | int    | `100`   | Number of patients to generate             |
| `--format <fmt>`              | string | `sql`   | Output format: `sql`, `csv`, `hl7`, `fhir` |
| `--geographic-focus <region>` | string | `us`    | Geographic distribution                    |
| `--seed <n>`                  | int    | Random  | Reproducible seed                          |
| `--output <path>`             | string | stdout  | Output file or directory                   |

```bash theme={null}
# Generate 1000 patients as SQL
pidgeon flock generate --count 1000 --format sql --output ./seed-data/

# Generate as FHIR bundles
pidgeon flock generate --count 500 --format fhir --output ./fhir-data/

# Reproducible output
pidgeon flock generate --count 1000 --format csv --seed 42
```

***

## pidgeon flock seed

Seed a connected database with generated data.

```bash theme={null}
pidgeon flock seed [options]
```

| Flag        | Type | Description                             |
| ----------- | ---- | --------------------------------------- |
| `--dry-run` | flag | Preview SQL without executing           |
| `--cleanup` | flag | Remove previously seeded synthetic data |

```bash theme={null}
# Preview what would be inserted
pidgeon flock seed --dry-run

# Seed the database
pidgeon flock seed

# Clean up synthetic data
pidgeon flock seed --cleanup
```

***

## pidgeon flock status

Check the status of a running generation job.

```bash theme={null}
pidgeon flock status
```