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.

Portable events in browser preview (next release)

Requires form0-core 0.5.1 or later within the supported 0.5.x range (installed with the CLI).

In the built-in browser preview, open Form Settings, enable Portable preview events, and select New record or Existing record explicitly. The option is off by default. Opening read-only runs load only; changing these settings starts a new editor session with accepted values. A schema reload retires the previous session rather than pretending the editor was closed.

The enabled preview evaluates effective values, runs load-record, then the selected new-record or edit-record. User field changes and enabled status changes run contextual events after queued updates settle; defaults, calculations and SETVALUE() do not create additional change events. Optional focus/blur apply to text and numeric controls; click applies to supported hyperlinks.

Submit runs built-in and synchronous INVALID(message) validation, then save-record once, and validates again only if pre-save values changed. Connectors receive that final prepared record. Custom findings are scope-level summary messages, separate from intrinsic state.errors and calculation diagnostics. Calculation errors alone add no save blocker. Prepare draft returns an invalid-capable raw snapshot and validation summary in the console; it does not submit to a connector or persist a draft. No saved-* schema event is added.

Inline rows have Edit, Save row and Cancel row controls in this mode. Opening uses repeatable lifecycle hooks; row Save validates and runs its pre-save hook before accepting local values. Ancestor/main reads are allowed, while SETVALUE() writes only inside that row. Cancel restores accepted data, including staged nested edits. Collapsing a row is presentation only. Accepted row membership changes notify the owner; failures in that later notification are reported without undoing acceptance. Closed-row evaluation keeps preview's existing recursive policy; this adds no binding submission-freshness or aggregation policy.

The generation-bound developer controller is window.form0PreviewEvents while an editor is active:

const prepared = await window.form0PreviewEvents.prepareSave({ intent: 'submit' });
const checked = await window.form0PreviewEvents.dispatch({ type: 'validate-record' });

These promises finish accepted operations/presentation and return findings/issues. Preparation never submits or closes. Row requests supply the complete instancePath and observed scopeId from the preview response/row's data-preview-scope-id; positional paths require that scope ID. The controller accepts JSON metadata, rejects executable/native-file payloads, and becomes obsolete on reload or closure. Existing IDs are used for attribution. Cancel/Close dispatch notifications before retirement; abrupt tab disposal does not manufacture schema close hooks. Reopen starts a new session. These settings apply to the built-in preview; serve --app retains app-owned behavior.

✅ 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