@openverb/cli

Command-line tools for the OpenVerb Framework.

Installation

npm install -g @openverb/cli

Or use with npx:

npx @openverb/cli --help

Commands

openverb validate [path]

Validate verb definitions.

# Validate all verbs in current directory
openverb validate

# Validate specific directory
openverb validate ./verbs

# Validate single file
openverb validate ./verbs/user.create.json

Output:

✓ user.create.json - Valid
✓ user.update.json - Valid
✗ todo.create.json - Invalid
  - inputSchema.properties.title: Required field missing
  - effects: Must be an array

openverb init [options]

Initialize OpenVerb in a project.

# Interactive setup
openverb init

# With options
openverb init --typescript --example todo

Options:

• --typescript - Use TypeScript
• --javascript - Use JavaScript
• --example <name> - Include example verbs (todo, user, blog)

Creates:

openverb/
├── verbs/           # Verb definitions
│   └── example.ping.json
├── handlers/        # Handler implementations
│   └── example/
│       └── ping.ts
└── runtime.ts       # Runtime configuration

openverb generate <type> <name>

Generate boilerplate code.

# Generate a verb + handler
openverb generate verb user.create

# Generate just a verb definition
openverb generate verb todo.update

# Generate a handler
openverb generate handler user/create

Generated files:

openverb/
├── verbs/
│   └── user.create.json    # Generated verb definition
└── handlers/
    └── user/
        └── create.ts       # Generated handler

Verb Validation Rules

The validator checks:

• ✅ Required fields: id, version, summary, handler
• ✅ Schema validation: inputSchema, outputSchema are valid JSON Schema
• ✅ Effects array: Valid effect names
• ✅ ID format: Follows namespace.action pattern
• ✅ Version format: Semantic versioning (e.g., 1.0.0)
• ✅ Handler path: Exists in handlers directory

Example Workflow

# 1. Initialize project
openverb init --typescript

# 2. Generate a new verb
openverb generate verb user.register

# 3. Edit the generated files
# openverb/verbs/user.register.json
# openverb/handlers/user/register.ts

# 4. Validate before deployment
openverb validate

# 5. Deploy your app!

Configuration

Create .openverbrc.json in your project:

{
  "verbsDir": "./openverb/verbs",
  "handlersDir": "./openverb/handlers",
  "typescript": true
}

Integration with Build Tools

package.json scripts

{
  "scripts": {
    "validate": "openverb validate",
    "generate": "openverb generate",
    "prebuild": "openverb validate"
  }
}

CI/CD

# .github/workflows/validate.yml
name: Validate Verbs
on: [push]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npx @openverb/cli validate

Related Packages

• @openverb/runtime - Execution runtime
• @openverb/policy - Policy engine
• @openverb/sdk - Client SDK

License

MIT