form0-cli

Note

form0 is in active development and is available to use today. Its schema format and core concepts are stable in practice, but releases before 1.0 may include breaking changes. Pin your versions and review the release notes when upgrading. A formally stable release is coming.

form0-cli is the canonical entry point for the form0 open-source ecosystem. It is an interactive command-line toolkit for creating projects and building, validating, previewing, testing, and serving form schemas locally.

📦 Installation

Install the CLI globally to get the form0 command:

npm install -g form0-cli

Or run without a global install:

npx form0-cli

Requires Node.js 22.19.0 or newer.

🚀 Quickstart

1. Start the interactive shell:

   form0

2. Initialize a standard project:

   • Run init
   • Choose Standard project
   • Let the CLI auto-load your schema (if it is the only schema in the project root)

3. Start the dev server:

   form0> serve
   

4. Open the live preview at http://localhost:3030 (or the port printed in the terminal).

What you get in a Standard project:

• form.schema.json with a starter form
• form0.config.js for CLI settings
• test.js for local engine checks
• supporting-images/ for field assets
• package.json and README.md scaffolding

Edit your first schema

This workflow assumes the dev server is running (serve) and the live preview is open.

1. Enter schema edit mode:

   form0(server)> schema edit
   

   Editor required: set EDITOR or VISUAL (for example, export EDITOR=code).

2. Preview the schema:

   form0(server,schema)> preview
   

3. Add a NumericField after a field by row id:

   form0(server,schema)> add NumericField after <id>
   

   Example template:

   {
     "data_name": "quantity",
     "label": "Quantity",
     "min": 1,
     "max": 100,
     "format": "integer"
   }

4. Add a CalculatedField after the new field:

   form0(server,schema)> add CalculatedField after <new-id>
   

   Example template:

   {
     "data_name": "total",
     "label": "Total",
     "display": { "style": "numeric" },
     "calculate": "$quantity * 2"
   }

5. Save and close your editor. The schema is saved and validated automatically.

6. Exit schema edit mode:

   form0(server,schema)> q
   

   Stop the dev server:

   form0(server)> serve stop
   

Command reference summary

AI authoring (preview)

Start directly with form0 ai [schema], or enter ai from the interactive shell. AI composes with the live server, so serve followed by ai produces a form0(server,ai)> prompt and broadcasts validated drafts to the browser without saving them.

The selected provider receives the complete form schema and installed form0 authoring catalog. Every change is a transient semantic mutation batch: inspect it with /preview or /diff, then use /apply or /discard. Writes require explicit approval, are atomic, and are rejected if the schema changed on disk. /undo stages the last saved version for approval.

Unchanged batches are rejected: they cannot create a pending proposal, save an unchanged file, or create undo history. A rejected revision preserves any existing valid draft. Revising a draft back to the saved schema clears the pending proposal without writing the file. The CLI reports the actual pending state independently of the assistant's text.

AI commands always start with /: use /model <provider>/<model>, not model <provider>/<model>. Without a selected model, requests show selection guidance rather than a zero-token context error.

Provider authentication and per-schema conversations are stored under ~/.form0-cli/ai/, not in projects or schemas. Pi exposes its provider catalog; the preview baseline covers OpenAI API keys and Codex OAuth, Anthropic API keys and Claude OAuth, Gemini API keys, OpenRouter key/OAuth, and local Ollama models. Environment credentials remain supported. Use /providers, /login, /model, and /privacy inside AI mode. /status shows the selected provider and model, locally configured authentication sources, draft state, schema path, cloud policy, and conversation persistence without contacting a provider. Use /model without an argument to show the current model.

The selected model is part of the per-schema Pi conversation and is restored when AI mode is re-entered. /new and /clear keep the current model for the new conversation. If that model is no longer available or authenticated, the CLI shows Pi's fallback warning instead of silently changing it.

While a request is running, the CLI displays [AI] Thinking with <provider>/<model>… and changes the prompt to form0(ai,busy)> (or form0(server,ai,busy)>). Natural-language input entered while busy is queued in order as follow-up requests; an empty Enter only redraws the prompt. /help, /status, /privacy, and /cancel remain available. /cancel stops the active request and clears queued follow-ups; other commands are unavailable until processing has finished.

ai.allowCloud: false on the form or any field blocks cloud models with no CLI override. Any requiresConsent: true asks before the first cloud request and after switching cloud providers. Otherwise provider selection counts as consent after the CLI states that the full schema is sent.

The agent may read relevant Markdown from https://docs.form0.dev, beginning at llms.txt; fetched text is untrusted supplementary guidance and installed core catalogs win on conflicts. There is no filesystem, shell, arbitrary web, extension, skill, MCP, image, or record-data access. Forms that do not fit completely in the selected model context are refused rather than truncated. Calculations and events are checked by form0-core before approval, but generated JavaScript still deserves review.

Pi SDK upgrade notes

The CLI pins both Pi SDK packages to 1.0.4. The Node.js requirement and the preview/approval workflow are unchanged; Pi's new built-in tools, MCP, and extensions are not enabled.

• Azure users: Pi renamed azure-openai-responses to azure. Update explicit provider/model references and custom provider configuration, then use /login if authentication needs to be renewed. The CLI does not automatically migrate credential files.
• Existing openai-codex OAuth remains available. The newer OpenAI ChatGPT sign-in method requests a stable installation ID during authentication. The CLI creates it only when requested and stores it privately in its AI settings. This integration does not enable Pi analytics.

Interactive shell (form0)

• init [dir] - Initialize a project (Standard/Web/Mobile)
• load / load <file> - Interactive load or load a specific schema file
• preview - Show the schema summary
• validate - Validate the current schema
• run [--values <input>] - Run the engine with optional values
• watch [--auto-run] [--auto-validate] - Watch schema changes
• serve [--app] [--port] [--host] - Start live preview; --app runs the app dev server from form0.config.js
• schema edit - Open the schema editor
• ai - Enter preview AI authoring mode
• schema import <csv> [--force] / schema export [csv] [--force] - Convert JSON ↔ CSV
• schema convert formio <json> [options] - Preview: Convert an exported Form.io form schema to form0
• schema keys - Generate missing field keys
• test [dir] - Run the test.js file in a project
• connector <action> - Manage connectors (install/configure/test/reload/status/remove/uninstall/list)
• values / fields - Show stored values or valid field names
• reload - Reload the current schema file
• status - Show the current session status
• clear / clear values - Clear screen or stored values
• theme [name] / locale [name] - View or change theme/locale
• help / exit - Help or quit

Standalone commands

form0 init [dir]
form0 validate <schema>
form0 preview <schema>
form0 run <schema> --values <json|string|file>
form0 watch [schema] --auto-run --auto-validate
form0 serve [schema] --port 3030 --host localhost --app
form0 schema import <csv> [-o <json>] [-f]
form0 schema export [csv] [-i <json>] [-f]
form0 schema convert formio <json> [-o <json>] [--report <json>] [--dry-run] [--allow-lossy] [-f]
form0 test [dir]
form0 connector <action> [name]
form0 theme [name]
form0 locale [name]
form0 interactive   # or: form0 shell
form0 ai [schema]   # preview AI authoring

Working with values

form0-cli accepts JSON strings or files for --values:

form0 run form.schema.json --values '{"name":"Alice","age":25}'
form0 run form.schema.json --values values.json
form0 run form.schema.json --values values.yaml

Invalid fields are filtered out with warnings based on the schema.

Calculation diagnostics

The next CLI release reports structured calculation diagnostics separately from field-validation errors. Diagnostic details go to stderr; evaluated state remains on stdout.

• Standalone validate exits 1 for structural failures or calculation-analyzer errors.
• Standalone run prints evaluated state and exits 1 if the runtime snapshot contains an error. Errors from intermediate calculation passes remain part of that evaluation.
• Warnings alone exit 0. Watch, serve, and interactive sessions remain available for recovery.
• --no-diagnostics suppresses calculation diagnostic details for validate, run, watch, and serve, including their interactive equivalents. Collection and command outcomes remain active.
• The built-in preview reports in the browser console, distinguishes nested rows, clears recovered findings, and reports recurrence without repeating identical findings.

These command outcomes do not change state.errors, submission validation, or reform draft saving. An app launched through serve --app retains its own reporting policy.

✅ Requirements

• Node.js 22.19.0+

📚 Documentation

• CLI overview
• Initialize a project
• Interactive shell
• Command reference
• Quickstart
• Full documentation

🔒 Security

The preview server is a local development tool: it loads configured connector modules and executes schema behavior. Use trusted projects and connectors. It binds to localhost by default; if you use --host to expose it to another interface, only do so on a trusted network.

Do not report suspected vulnerabilities through public issues. See SECURITY.md for private reporting instructions.

🔗 Related repositories

• form0-core - Core form engine
• form0-react - React components
• form0-react-native - React Native components

🤝 Support and contributing

See SUPPORT.md for help and CONTRIBUTING.md to contribute.

📄 License

MIT