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

PreviousReact ComponentsNextDashboard

Last updated