CLI

Overview

The formr-cli is a development tool for managing forms locally, validating schemas, and syncing with the API. It helps you work with forms in your development workflow.

Installation

Use via npx (no installation required):

npx formr-cli <command>

Or install globally:

npm install -g formr-cli

Authentication

Login

Authenticate with the Formr API:

npx formr-cli login

This will prompt for your API key and save it to ~/.formr/config.json.

Commands

init

Initialize Formr in your project.

npx formr-cli init

Creates a .formr directory with configuration files.

What it does:

• Creates .formr directory

• Sets up configuration files

• Prepares project for form development

---

infer

Infer form contract from HTML file or URL.

npx formr-cli infer ./public/contact.html --form contact
npx formr-cli infer https://example.com/form.html --form contact

This analyzes an HTML form and generates a Formr schema automatically.

Use cases:

• Migrate existing HTML forms

• Convert forms from other systems

• Quick form schema generation

---

validate

Validate form contract.

npx formr-cli validate
npx formr-cli validate ./forms/contact.formr.json

Validates form schemas for errors and issues before pushing to the API.

Checks:

• Schema structure

• Field definitions

• Validation rules

• Required fields

---

push

Push form contract to API.

npx formr-cli push
npx formr-cli push ./forms/contact.formr.json --apply

Uploads local form schemas to the API. Use --apply to update existing forms.

Behavior:

• Creates new forms if they don't exist

• Shows warning if form exists (use --apply to update)

• Updates existing forms when --apply is used

---

diff

Show diff between local and remote form.

npx formr-cli diff contact
npx formr-cli diff contact ./forms/contact.formr.json

Compares local form schema with the version on the API to see what has changed.

Use cases:

• Review changes before pushing

• See what's different between local and remote

• Verify updates

---

pull

Pull form contract from API.

npx formr-cli pull contact
npx formr-cli pull contact --format yaml
npx formr-cli pull contact --format ts

Downloads form schemas from the API. Supports multiple formats:

• JSON (default)

• YAML

• TypeScript

Use cases:

• Sync remote forms to local

• Export forms for version control

• Generate TypeScript types

---

types

Generate TypeScript types from forms.

npx formr-cli types
npx formr-cli types --out ./types/formr.d.ts

Generates TypeScript type definitions for your forms based on their schemas.

Output:

• Type definitions for form fields

• Answer types

• Form schema types

---

dev

Start dev server with mock submit and preview.

npx formr-cli dev
npx formr-cli dev --port 7801

Starts a local development server for testing forms without submitting to the API.

Features:

• Preview forms locally

• Mock form submissions

• Hot reload

• Development-friendly workflow

---

Configuration

Store API credentials in ~/.formr/config.json or use environment variables:

• FORMR_API_KEY - API key

• FORMR_API_URL - API URL (default: https://api.formr.dev)

Config File Location

~/.formr/config.json

Environment Variables

export FORMR_API_KEY="sk_live_..."
export FORMR_API_URL="https://api.formr.dev"

Workflow Examples

Complete Development Workflow

# 1. Initialize project
npx formr-cli init

# 2. Infer form from HTML
npx formr-cli infer ./public/contact.html --form contact

# 3. Validate schema
npx formr-cli validate

# 4. Push to API
npx formr-cli push --apply

# 5. Generate TypeScript types
npx formr-cli types

Updating Existing Forms

# 1. Pull latest from API
npx formr-cli pull contact

# 2. Make local changes
# Edit forms/contact.formr.json

# 3. Check differences
npx formr-cli diff contact

# 4. Validate changes
npx formr-cli validate

# 5. Push updates
npx formr-cli push --apply

Local Development

# 1. Start dev server
npx formr-cli dev

# 2. Preview forms at http://localhost:7800
# 3. Test submissions locally
# 4. When ready, push to API
npx formr-cli push --apply

File Structure

After running init, your project will have:

.
├── .formr/
│   └── config.json
└── forms/
    └── *.formr.json

Next Steps

• Development Tools - Other development tools

• SDK Guide - JavaScript/TypeScript SDK

• React Components - React components

• API Reference - Complete API documentation