formfiller-cli

Parse any HTML form, detect field types intelligently, and generate realistic fake data — all from the terminal, no browser required.

Built as a companion CLI to formfillerapp.com.

Install

Requires Node.js 22+.

# global install
pnpm add -g formfiller-cli

# or run directly without installing
pnpm dlx formfiller-cli analyze ./my-form.html

Help

formfiller --help          # list all commands
formfiller analyze --help  # flags for a specific command
formfiller fill --help

Commands

analyze — inspect a form

Parses a URL or local HTML file and shows detected field types with sample values.

formfiller analyze <url|file> [--json] [--form <n>]

$ formfiller analyze http://localhost:3000/signup

Form #1 — POST /signup
┌─────────────────────┬──────────┬─────────────┬──────────────────────────┐
│ Field               │ Type     │ Detected as │ Sample value             │
├─────────────────────┼──────────┼─────────────┼──────────────────────────┤
│ first_name          │ text     │ firstName   │ Marcus                   │
│ email               │ email    │ email       │ [email protected] │
│ password            │ password │ password    │ xK9#mP2$vL8n             │
│ confirm_password    │ password │ password    │ xK9#mP2$vL8n             │
│ subject             │ text     │ random      │ gah                      │
│ message             │ textarea │ random      │ Vestrum ex admitto...    │
│ country             │ select   │ random      │ us                       │
└─────────────────────┴──────────┴─────────────┴──────────────────────────┘
  ⚠  3 field(s) not detected — add name/id/label attributes to improve detection

Flags:

| Flag | Description | |------|-------------| | --json | Output as JSON (machine-readable, useful for agents) | | --form <n> | Target a specific form on the page (1-based, default: all) |

generate — produce fake records

Generates N fake data records based on the form's field schema. Outputs JSON or CSV.

formfiller generate <url|file> [--count <n>] [--output json|csv] [--form <n>]

# Single record (default)
$ formfiller generate ./signup.html

# 50 records as JSON — pipe into your DB seeder
$ formfiller generate http://localhost:3000/signup --count 50 > seed.json

# CSV output
$ formfiller generate ./signup.html --count 100 --output csv > seed.csv

Flags:

| Flag | Default | Description | |------|---------|-------------| | -n, --count <n> | 1 | Number of records to generate | | -o, --output <format> | json | Output format: json or csv | | --form <n> | 1 | Target form number (1-based) |

fill — fill and submit a form

Generates a payload for a form and optionally submits it via HTTP POST. Exit code is non-zero on failure — usable in CI scripts.

formfiller fill <url> [--submit] [--expect <text>] [--dry-run] [--verbose] [--form <n>]

# Inspect what would be submitted (no network request)
$ formfiller fill http://localhost:3000/signup --dry-run

# Override specific fields, auto-fill the rest
$ formfiller fill http://localhost:3000/register \
    --field username=test-bot \
    --field [email protected] \
    --dry-run

# Submit and check for success
$ formfiller fill http://localhost:3000/signup --submit --expect "Welcome"

# Verbose: see the full request and response
$ formfiller fill http://localhost:3000/signup --submit --verbose

--field is repeatable. Overridden fields are shown with (override) in dry-run output.

Flags:

| Flag | Description | |------|-------------| | --submit | POST the form data to the action URL | | --expect <text> | Exit 1 if the response does not contain this text | | --dry-run | Print the payload without submitting | | --verbose | Show the full request body and response | | --field <name=value> | Override a specific field value (repeatable) | | --form <n> | Target form number (1-based, default: 1) |

Confirmation fields (password2, confirmPassword, emailConfirm, etc.) are automatically detected and filled with the same value as their original field — no manual override needed.

$ formfiller fill http://localhost:3000/register --field username=test-bot --dry-run

  username:  test-bot                      (override)
  email:     [email protected]
  password:  xK9#mP2$vL8n
  password2: xK9#mP2$vL8n                  ← matches password automatically

Field Detection

Fields are detected by matching name, id, label, and placeholder attributes against a keyword map. The following types are detected automatically:

| Detected as | Triggers | |-------------|----------| | firstName | firstname, fname, first_name, given_name | | lastName | lastname, lname, last_name, family_name | | fullName | fullname, name, full_name | | email | email, mail, e_mail, or type="email" | | phone | phone, telephone, mobile, tel | | address | address, street, location, residence | | city | city, town | | state | state, province | | zipCode | zip, zipcode, postal_code, postcode | | company | company, organization, business | | jobTitle | title, position, jobtitle, role | | username | username, user_name, login, handle | | birthDate | birth, birthday, dob, date_of_birth | | password | type="password" | | url | type="url" |

Undetected fields fall back to context-aware random generation based on their HTML type (text, number, date, textarea, select, etc.).

Use with AI coding agents

formfiller is designed to be agent-friendly. After writing a form, an agent can:

# Verify field detection
formfiller analyze ./src/SignupForm.html --json

# Generate seed data for a new model
formfiller generate ./src/SignupForm.html --count 50 > seed.json

# Smoke test after dev server starts
formfiller fill http://localhost:3000/signup --submit --expect "201"

The --json flag on analyze returns structured output that agents can parse and act on.

Limitations

• Static HTML only — JavaScript-rendered forms (React, Vue, etc.) are not supported. Point at a URL that serves the raw HTML, or use a local .html file.
• No auth/sessions — cookies and authentication flows are not handled.
• No multi-step forms — wizard-style forms that span multiple pages are not supported.