form0-cli

[!WARNING] form0 is in active, very early development. Do not use in production. Expect breaking changes and unstable behavior.

form0-cli is the interactive command-line toolkit for building, validating, previewing, and serving schemas in the form0 open-source ecosystem. It powers the local development workflow for form0 projects.

🗂️ Documentation

• Quickstart: https://docs.form0.dev/getting-started/quickstart
• Edit your first schema: https://docs.form0.dev/getting-started/schema-edit
• Full docs: https://docs.form0.dev

⚙️ Installation

Install the CLI globally to get the form0 command:

npm install -g form0-cli

Or run without a global install:

npx form0-cli

🚀 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

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
• schema import <csv> [--force] / schema export [csv] [--force] - Convert JSON ↔ CSV
• 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 test [dir]
form0 connector <action> [name]
form0 theme [name]
form0 locale [name]
form0 interactive   # or: form0 shell

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.

Requirements

• Node.js 18+

Related repositories

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

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.