form0-cli

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

🚀 Quickstart

• Start the interactive shell:

  form0
  

• 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)

• Start the dev server:

  form0> serve
  

• 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.

• Enter schema edit mode:

  form0(server)> schema edit
  

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

• Preview the schema:

  form0(server,schema)> preview
  

• 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"
  }
  

• 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"
  }
  

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

• 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 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

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 22+

📚 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