OpenForm is documents as code. The CLI provides a registry-first workflow for installing, managing, and creating OpenForm artifacts — forms, documents, checklists, and bundles.

Package overview

• 📦 Registry-first — Install artifacts from public or private registries
• 🔍 Search & discover — Find artifacts by name, kind, or tags
• 🏗️ Project management — Initialize projects with proper configuration
• ✏️ Authoring tools — Create and validate your own artifacts
• 🔒 Lock file support — Reproducible installations across environments
• 🌐 Private registries — Authenticate with custom headers and tokens

Installation

npm install -g @open-form/cli

Or use with npx:

npx @open-form/cli --help

Quick start

# Initialize a new project
ofm init my-project
cd my-project

# Search for artifacts
ofm search "lease agreement"

# Install an artifact
ofm add @acme/residential-lease

# List installed artifacts
ofm list

# View artifact details
ofm view @acme/residential-lease

Commands

Registry commands

| Command | Description | |---------|-------------| | ofm add <artifact> | Install an artifact from a registry | | ofm list | List installed artifacts | | ofm view <artifact> | View details of an installed artifact | | ofm search [query] | Search for artifacts in a registry |

Registry management

| Command | Description | |---------|-------------| | ofm registry add <namespace> <url> | Add a registry | | ofm registry remove <namespace> | Remove a registry | | ofm registry list | List configured registries | | ofm registry info <namespace> | Show registry details |

Authoring commands

| Command | Description | |---------|-------------| | ofm new form <name> | Create a new form | | ofm new document <name> | Create a new document | | ofm new checklist <name> | Create a new checklist | | ofm new bundle <name> | Create a new bundle | | ofm validate <artifact> | Validate an artifact | | ofm fix <artifact> | Fix artifact metadata |

Project commands

| Command | Description | |---------|-------------| | ofm init [directory] | Initialize a new project | | ofm render <artifact> | Render an artifact layer | | ofm show <artifact> | Display artifact structure | | ofm diff <file1> <file2> | Compare two artifacts |

Installing artifacts

Install artifacts from any configured registry:

# Basic install
ofm add @acme/residential-lease

# Install with layers (templates, PDFs, etc.)
ofm add @acme/residential-lease --layers all

# Install specific layers
ofm add @acme/residential-lease --layers default,pdf-template

# Choose output format
ofm add @acme/residential-lease --format json

# Force reinstall
ofm add @acme/residential-lease --force

Artifacts are referenced using scoped names: @namespace/artifact-name

Searching registries

# Search by keyword
ofm search "lease agreement"

# Search a specific registry
ofm search --registry @acme

# Filter by artifact kind
ofm search --kind form

# Filter by tags
ofm search --tags real-estate,california

# Output as JSON (for scripting)
ofm search --json

Managing registries

Add registries to your global or project configuration:

# Add a public registry (prompts for location when in a project)
ofm registry add @acme https://registry.acme.com

# Add to global config explicitly
ofm registry add @acme https://registry.acme.com --global

# Add to project config explicitly
ofm registry add @acme https://registry.acme.com --project

# Add with authentication
ofm registry add @private https://registry.private.com \
  --header "Authorization: Bearer \${PRIVATE_TOKEN}"

# List all registries
ofm registry list

# Remove a registry
ofm registry remove @acme

Configuration

Project configuration

Created when you run ofm init. Located at open-form.json in your project root.

{
  "$schema": "https://schema.open-form.dev/manifest.json",
  "name": "@myorg/my-project",
  "title": "My OpenForm Project",
  "visibility": "private",
  "registries": {
    "@acme": "https://registry.acme.com"
  },
  "artifacts": {
    "dir": "artifacts",
    "format": "yaml"
  }
}

Global configuration

User-level settings at ~/.open-form/config.json. Applies to all projects.

{
  "$schema": "https://schema.open-form.dev/config.json",
  "registries": {
    "@acme": "https://registry.acme.com",
    "@private": {
      "url": "https://registry.private.com",
      "headers": {
        "Authorization": "Bearer ${PRIVATE_TOKEN}"
      }
    }
  },
  "defaults": {
    "format": "yaml",
    "artifactsDir": "artifacts"
  }
}

Environment variables in ${VAR_NAME} format are automatically expanded.

Configuration precedence

1. Project config — checked first
2. Global config — fallback
3. Built-in defaults

Project structure

my-project/
├── open-form.json           # Project manifest
├── .open-form/
│   └── lock.json            # Lock file (commit this)
└── artifacts/
    └── @acme/
        ├── residential-lease.yaml
        └── commercial-lease.yaml

Lock file

The .open-form/lock.json file tracks installed artifacts with their versions and integrity hashes. This ensures reproducible installations. Commit this file to version control.

Related packages

• @open-form/sdk — All-in-one SDK package
• @open-form/core — Core artifacts and builders
• @open-form/schemas — JSON Schema definitions
• @open-form/renderers — PDF, DOCX, Text renderers

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.

License

This project is licensed under the MIT license.

See LICENSE for more information.