CLI Reference

The norq CLI is a single binary that handles all Norq operations: project setup, linting, compilation, testing, preview, sending, code generation, and editor integration.

Installation

cargo install norq        # Rust
npm install -g norq       # Node.js
pip install norq          # Python
curl -fsSL https://norq.sh/install.sh | sh  # Universal

Commands

norq init

Create a new Norq project in the current directory.

norq init              # minimal project (config only)
norq init --example    # project with example templates

Creates norq.config.yaml and notifications/ directory with system/, transactional/, and promotional/ type folders. With --example, adds three ready-to-use notifications:

Each notification includes data.schema.yaml, data.samples.yaml, and tests.yaml.

norq new

Scaffold a new notification directory.

norq new transactional/order-shipped
norq new transactional/order-shipped --channels email,sms,slack
norq new promotional/marketing/promotions/welcome-offer --channels email

Creates:

notifications/transactional/order-shipped/
  email.md
  sms.md
  slack.md
  data.schema.yaml
  data.samples.yaml
  tests.yaml

The --channels flag controls which channel template files are created. Without it, only email is scaffolded.

The first segment must be a notification type (system, transactional, or promotional). Within each type folder, supports category/subcategory paths with / separators (up to 4 segments: type/category/subcategory/name). Each segment must match [a-z0-9]+(-[a-z0-9]+)* (lowercase, hyphen-separated). Intermediate directories are created automatically.

norq lint

Lint notification templates for structural and content issues.

norq lint                                # all notifications
norq lint transactional/order-shipped    # one notification
norq lint --json           # JSON output (for CI/tooling)

Checks:

• Valid notification directory names
• No duplicate channel files (both .md and .json)
• Valid data schema (JSON Schema compliance)
• Sample data validates against schema
• Nullable-access warnings (variables used without :::if guard)
• Raw expression warnings ({{{triple-curly}}})
• Parse errors

norq compile

Compile a notification template into channel payloads.

norq compile transactional/welcome --json
norq compile transactional/welcome --channel email --json
norq compile transactional/welcome --sample "New user" --json
norq compile transactional/welcome --data ./data.json --json
norq compile transactional/welcome --channel email --sample "New user" --json

If neither --data nor --sample is provided, the first sample is used automatically.

norq test

Run assertion tests defined in tests.yaml.

norq test                                # all notifications
norq test transactional/order-shipped    # one notification
norq test --json           # JSON output

See the testing page for test syntax and assertion operators.

norq preview

Preview compiled output for a specific channel.

norq preview transactional/welcome --channel email
norq preview transactional/welcome --channel email --sample "Pro user"
norq preview transactional/welcome --channel email --terminal

norq send

Compile and send a notification via configured providers.

norq send transactional/welcome --to '{"email":"user@example.com"}' --sample "New user"
norq send transactional/welcome --to '{"email":"user@example.com"}' --data ./data.json
norq send transactional/welcome --to '{"email":"user@example.com","phone":"+1234567890"}' --channels email,sms
norq send transactional/welcome --to '{"email":"user@example.com"}' --dry-run

norq dev

Start a preview dev server with hot reload.

norq dev                              # all notifications, port 3456
norq dev transactional/welcome        # specific notification
norq dev --port 8080       # custom port

The dev server provides a web UI where you can:

• Switch between notifications and channels
• Select different sample data
• See live updates as you edit templates

norq doctor

Validate project health.

norq doctor

Checks:

• norq.config.yaml exists and is valid
• Notifications directory exists
• All notification directories are valid
• Schema and sample files are well-formed
• Provider configuration (if present) is valid

norq codegen

Generate type-safe SDK bindings from data schemas.

norq codegen                           # use config file targets
norq codegen --lang typescript --out src/generated/norq.ts
norq codegen --check                   # CI: verify files are up to date

Without --lang/--out, reads targets from the codegen section of norq.config.yaml.

norq lsp

Start the Language Server Protocol server on stdin/stdout.

norq lsp

Used by editor extensions (VS Code, Neovim, etc.). Not typically run manually. See the editor setup page.

norq mcp-server

Start the Model Context Protocol server on stdin/stdout.

norq mcp-server

Used by AI agents and coding assistants. See the AI integration page.

norq completions

Generate shell completions for bash, zsh, fish, elvish, or PowerShell.

norq completions bash >> ~/.bashrc
norq completions zsh >> ~/.zshrc
norq completions fish > ~/.config/fish/completions/norq.fish
norq completions elvish >> ~/.elvish/rc.elv
norq completions powershell >> $PROFILE

norq version

Show version information.

norq version
norq version --json

Configuration

All project configuration lives in norq.config.yaml:

notifications: ./notifications
 
providers:
  resend:
    package: "@norq/provider-resend"
    config:
      api_key: ${RESEND_API_KEY}
      from: "notifications@myapp.com"
 
routing:
  email: resend
  sms: suprsend
 
codegen:
  - lang: typescript
    out: src/generated/norq.ts

Environment variables use ${VAR_NAME} syntax and are substituted at load time.

Exit codes