datalab-cli 0.1.0

# fill

Fill a form with provided field data.

## Synopsis

```
datalab fill [OPTIONS] <FILE|URL> --fields <JSON>
```

## Description

Fill PDF or image forms with data. The CLI matches field names to form fields and fills them with the provided values. Returns the filled form as a binary file.

---

## Arguments

| Argument | Description |
|----------|-------------|
| `<FILE\|URL>` | File path or URL of the form to fill |

---

## Options

### Field Options

| Option | Description |
|--------|-------------|
| `--fields <JSON>` | JSON file path or inline JSON mapping field names to values **(required)** |

### Matching Options

| Option | Description | Default |
|--------|-------------|---------|
| `--confidence-threshold <THRESHOLD>` | Field matching strictness (0.0-1.0) | `0.5` |
| `--context <TEXT>` | Additional context for field matching | - |

### Processing Options

| Option | Description | Default |
|--------|-------------|---------|
| `--max-pages <N>` | Maximum pages to process | - |
| `--page-range <RANGE>` | Page range (e.g., `"0-5,10"`) | - |
| `--timeout <SECS>` | Request timeout in seconds | `300` |

### Output Options

| Option | Description |
|--------|-------------|
| `-o, --output <FILE>` | Write filled form to file **(required for binary output)** |

### Cache Options

| Option | Description |
|--------|-------------|
| `--skip-cache` | Skip local cache lookup |

---

## Field Data Format

The fields parameter maps field names to values:

```json
{
  "field_name": "value",
  "another_field": "another value"
}
```

Field names are matched to form fields using fuzzy matching. Use `--confidence-threshold` to control matching strictness.

---

## Examples

### Basic Form Filling

```bash
# Inline field data
datalab fill application.pdf \
  --fields '{"name": "John Doe", "email": "john@example.com"}' \
  --output filled.pdf
```

### Fields from File

```bash
# Using a JSON file
datalab fill application.pdf --fields data.json --output filled.pdf
```

Where `data.json` contains:
```json
{
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-15",
  "address": "123 Main St, Anytown, USA",
  "phone": "555-123-4567",
  "email": "john.doe@example.com"
}
```

### With Context

Provide context for ambiguous fields:

```bash
datalab fill tax-form.pdf \
  --fields '{"name": "John Doe", "ssn": "123-45-6789"}' \
  --context "This is a W-2 tax form" \
  --output filled.pdf
```

### Adjusting Match Threshold

Lower threshold for lenient matching:

```bash
datalab fill form.pdf \
  --fields data.json \
  --confidence-threshold 0.3 \
  --output filled.pdf
```

Higher threshold for strict matching:

```bash
datalab fill form.pdf \
  --fields data.json \
  --confidence-threshold 0.8 \
  --output filled.pdf
```

---

## Confidence Threshold

The confidence threshold controls how strictly field names must match:

| Threshold | Description |
|-----------|-------------|
| `0.0 - 0.3` | Very lenient, matches fields with loose similarity |
| `0.4 - 0.6` | Balanced (default), reasonable fuzzy matching |
| `0.7 - 1.0` | Strict, requires close or exact matches |

---

## Output

When using `--output`, the filled form is saved to the specified file:

```bash
datalab fill form.pdf --fields data.json --output filled.pdf
```

The JSON output includes metadata about the fill operation:

```json
{
  "filled_fields": 5,
  "unmatched_fields": ["unknown_field"],
  "output_file": "filled.pdf"
}
```

---

## Related Commands

- [`convert`](convert.md) - Convert filled forms to markdown
- [`extract`](extract.md) - Extract data from forms

---

## See Also

- [Filling Forms Tutorial](../tutorials/fill-forms.md)