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

Coming soon. Package registry distribution is not yet available. See norq.sh for updates. To build from source: make install (requires Rust toolchain).

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
  data.schema.yaml
  data.samples.yaml

The --channels flag controls which channel template files are created. Without it, only email.md is scaffolded. With --channels email,sms,slack, the directory also includes sms.md and slack.md.

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 structure, syntax, and deliverability issues.

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

Output is sorted by max severity per file (Error-bearing files first, then Warning-bearing, then Info-only), then by severity within each file, then by line number. norq lint exits non-zero when any diagnostic has severity Error.

Norq checks 96 rules across structure, template syntax, accessibility, brand health, and channel-specific deliverability:

Brand lint rules (run once per project against brand.yaml):

email/low-contrast is also extended to scan brand.styles.* bundles that declare both bg and color – references resolve through the brand, so a style like { bg: "{colors.brand}", color: "{colors.body}" } will fire if the resolved pair fails WCAG AA.

Template attr token rules (run on every directive param + block attr):

These rules supersede the older template/invalid-attr-value for bg/color keys – attr values that previously rendered as empty backgrounds now fail the lint with an actionable message.

Push lint rules:

See Lint Rules for the complete reference with descriptions, severity levels, and fix guidance.

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.

Strict mode is on by default. It refuses to emit output when the template references data missing from the supplied data object, uses an unknown pipe, or passes a wrong-type pipe argument. Opt out per-invocation with --no-strict, or set strict: false in norq.config.yaml for a project-wide opt-out. See Strict mode below.

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 render

Render email previews and device screenshots via a render-capable provider. Subcommands:

norq render preview

Render an email to a single image (desktop or mobile viewport).

norq render preview transactional/welcome
norq render preview transactional/welcome --device mobile
norq render preview transactional/welcome --dark-mode --out preview.png
norq render preview transactional/welcome --sample "Pro user" --device mobile

norq render screenshot

Render an email as it appears in a specific email client.

norq render screenshot transactional/welcome --client gmail_web
norq render screenshot transactional/welcome --client outlook_2021 --out screenshot.png
norq render screenshot transactional/welcome --client iphone_15 --sample "New user"

Both render subcommands require a provider with render capabilities. Currently only the suprsend built-in provider supports rendering (preview + screenshot). If no render-capable provider is configured, you’ll see:

Error: Provider 'console' does not support op 'preview'

Configured providers:
  console          → no render

Hint: rendering requires a provider with render capabilities.
  Built-in: set NORQ_SUPRSEND_WORKSPACE_KEY to enable SuprSend (supports preview + screenshot)

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","cc":["audit@example.com"]}' --channels email
norq send transactional/welcome --to '{"email":"user@example.com"}' --idempotency-key "order-shipped-ORD-123"
norq send transactional/welcome --to '{"email":"user@example.com"}' --dry-run

Strict mode is on by default. A Handlebars-inspired pre-send validator refuses to deliver when the template references data missing from the runtime data object, uses an unknown pipe, or passes a wrong-type pipe argument. This catches silent data-corruption bugs (typo’d variable names, etc.) before they reach the recipient. See Strict mode.

CLI push limitations. The CLI is for development. It can send push only via providers that use static bearer tokens (e.g. expo with an access token). It cannot:

• Sign Apple JWT for APNs (also: ureq is HTTP/1.1 only — APNs requires HTTP/2).
• Exchange Google service-account credentials for FCM access tokens.
• Encrypt Web Push payloads.

For those providers, use an SDK. The CLI emits provider/cli-http2-required, provider/cli-oauth2-not-supported, or provider/cli-vapid-not-supported if you try.

Strict mode

Inspired by Handlebars’ strict mode. A pre-compile runtime validator refuses to send a notification when the template references data missing from the runtime data object, uses unknown pipes, or passes wrong-type pipe arguments.

On by default. Set strict: false in norq.config.yaml for a project-wide opt-out, or pass --no-strict per-invocation.

Legitimate exceptions that strict mode allows:

• :::if path — paths used inside the consequent are implicitly guarded.
• :::each items as item — loop binding is in scope inside the body.
• {{ path | default "..." }} — the default pipe makes missing paths OK.
• Explicit null — {"field": null} in data is allowed (distinct from “missing field”).

Violations surface as:

• undefined-runtime-path — expression path not in runtime data
• unknown-pipe — pipe name not in KNOWN_PIPES
• invalid-pipe-arg — pipe called with wrong type or arity

All three are reported with line numbers (remapped from expanded-doc coords through any partial expansions back to source coords).

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

Diagnose project environment, configuration, and health. Output is grouped into sections with three status levels: [✓] pass, [!] warning, [✗] error.

norq doctor                # human-readable grouped output
norq doctor --json         # machine-readable JSON (for CI/tooling)

Sections and diagnostics:

Example output:

Discovery
  [✓] Found norq project at ./

Environment
  [✓] norq v0.1.0-alpha.1

Project
  [✓] norq.config.yaml found and valid
  [✓] 3 notification(s) (1 promotional, 2 transactional)
  [✓] Routing: email → console, sms → console
  [✓] Providers: console

Health
  [✓] Lint: 0 error(s), 0 warning(s)
  [✓] Schema coverage: 3/3 notifications
  [!] Test coverage: 1/3 notifications
      Create tests.yaml in missing notification dirs
  [✓] Partials: email-footer, email-header

Project health: 1 warning(s)

Exit codes:

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 add

Add notifications and partials from registries or Git repositories.

norq add welcome
norq add @acme/invoice --overwrite
norq add github:user/repo/notifications/transactional/welcome
norq add welcome invoice --dry-run

Accepts bare names (welcome), namespaced names (@acme/welcome), full URLs, or Git shorthand (github:owner/repo/path[@ref]). Multiple items can be added in one call.

Dependency resolution: When a registry item declares registryDependencies, norq add recursively fetches all transitive dependencies, topologically sorts them (dependencies before dependents), and writes files in dependency order. Partials are installed to the notification-local _shared/ directory. Circular dependencies are detected and reported as errors. Existing partials with the same name are not overwritten unless --overwrite is passed.

norq registry

Manage and query notification registries. Subcommands:

norq registry build

Build registry.json into static JSON files for hosting.

norq registry build
norq registry build --out dist/registry --json

norq registry validate

Validate a registry manifest and all referenced items.

norq registry validate
norq registry validate --json

norq registry search

Search across configured registries.

norq registry search welcome
norq registry search invoice --type transactional
norq registry search --category account

norq registry list

List all items in configured registries.

norq registry list
norq registry list --type promotional --json

norq registry view

View details of a specific registry item.

norq registry view welcome
norq registry view @acme/invoice --files --json

norq provider

Manage providers and channel routing. Subcommands:

norq provider list

List all registered providers and their configuration status.

norq provider list

Output columns:

STATUS values:

Built-in providers

Config-driven setup is preferred. Example:

# norq.config.yaml
providers:
  resend:
    config:
      api_key: ${RESEND_API_KEY}
      from: norq@alerts.example.com
      from_name: "Example"
      reply_to: support@example.com
routing:
  email: resend

Env-var fallback exists for backward compatibility — when providers.resend is absent from the config, the CLI falls back to NORQ_RESEND_* env vars and reports configured (env).

norq provider routing

Show the channel-to-provider routing table. Displays which provider handles each channel and why.

norq provider routing

Output columns:

Resolution order: explicit routing config in norq.config.yaml takes priority, then first-match by registration order.

norq fmt

Format all template files in the project with canonical indentation and spacing.

norq fmt                   # format all .md files in notifications/
norq fmt --check           # check formatting without writing (exit 1 if changes needed)

The formatter enforces:

• 2-space indent inside directives, +2 for each nesting level
• One blank line between block-level elements
• No trailing blank lines before ::: closers
• No multiple consecutive blank lines
• Frontmatter and code blocks preserved as-is

Use --check in CI to enforce consistent formatting:

# GitHub Actions
- run: norq fmt --check

The LSP also supports document formatting (Format Document) using the same rules.

norq brand

Manage the project’s brand.yaml – the tenant’s visual identity (colors, typography, spacing, radii, styles, fonts, voice). Five subcommands cover the authoring lifecycle:

norq brand init                       # scaffold brand.yaml from defaults
norq brand show [--json]              # print resolved brand (aliases + pipes flattened)
norq brand import <file> [--out X]    # convert DESIGN.md / DTCG / Figma / Style Dictionary
norq brand export --format <fmt>      # emit dtcg | tailwind | css | json
norq brand diff <left> <right>        # semantic diff between two brand files

norq brand init

norq brand init                       # writes <config-dir>/brand.yaml
norq brand init --path ./design/brand.yaml
norq brand init --force               # overwrite an existing file

The scaffolded file is the compiled-in default brand (mirrors the previous flat theme: palette). Edit it to customise tokens.

norq brand show

norq brand show                       # human-readable summary
norq brand show --json                # ResolvedBrand JSON for scripting

Prints the brand the project will compile against – aliases like {colors.brand} and color pipes like {colors.brand | darken 10%} are flattened to literal values. Diagnostics from the resolver (broken refs, unknown pipes, basedOn cycles) are listed at the end.

norq brand import

norq brand import DESIGN.md                 # writes <config-dir>/brand.yaml
norq brand import tokens.json --out custom.yaml
norq brand import figma.json --stdout       # print YAML, don't write

Format detection is content-driven first, extension-only as a tiebreaker. Recognised inputs:

The DESIGN.md importer is regex-driven over Markdown. It pulls colors from bullet lines that contain a hex literal, dimensions from numbered bullets under ## Spacing / ## Border radius headers, and voice principles from bullets under ## Voice / ## Tone / ## Principles. Hit rate varies by source – the importer prints per-section counts so you can see what was recognised; missing groups stay empty for manual fill-in.

norq brand export

norq brand export --format dtcg              # to stdout
norq brand export --format tailwind --out tailwind.config.js
norq brand export --format css --out brand.css
norq brand export --format json

Pipe expressions ({colors.brand | darken 10%}) are pre-resolved before export. DTCG has no concept of computed tokens, so the exported file is a snapshot – a subsequent brand import reads the literal hex, not the pipe expression.

norq brand diff

norq brand diff old.yaml new.yaml

Semantic diff: walks colors, spacing, radii, typography structurally and reports add (+), remove (-), and change (~) per token. Token reorderings inside the YAML produce no noise – only token-name and value changes show up. Defaults are NOT merged; the diff shows only what is literally written in each file.

norq brand sync-agents

Generates AGENTS_BRAND.md – a single Markdown file every AI agent reads – from the resolved brand. The file lives at the project root (next to norq.config.yaml) and is regenerated on demand. Source-of-truth is brand.yaml; AGENTS_BRAND.md is a human- and agent-readable derivative.

norq brand sync-agents                      # write <config-dir>/AGENTS_BRAND.md
norq brand sync-agents --check              # CI mode: exit 1 if regen would change the file
norq brand sync-agents --stdout             # print, don't write
norq brand sync-agents --scope rules        # subset
norq brand sync-agents --out X.md           # custom path

The output is deterministic – same brand + same scope produces the same bytes – so --check does a byte-for-byte comparison without depending on diff tooling.

norq doctor runs the same check and warns when AGENTS_BRAND.md is stale relative to brand.yaml. norq init appends a ## Visual identity pointer to existing AGENTS.md / CLAUDE.md files at the project root (it does not create them). The pointer is stable text and never churns – the regeneratable file carries the churn.

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

Global flags

These flags work on all commands:

Configuration

All project configuration lives in norq.config.yaml:

notifications: ./notifications
 
providers:
  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.

Providers

Providers handle sending notifications to channels and rendering previews. Norq ships with seven built-in providers — three general-purpose plus four push-specialist:

Built-in providers are auto-registered when their env vars are set. Console is always registered as a fallback.

Custom providers

Define custom providers under providers: in norq.config.yaml. A custom provider specifies which channels it supports, authentication, and HTTP request definitions for each operation:

providers:
  mailgun:
    channels: [email]
    config:
      domain: { required: true }
      api_key: { required: true, secret: true }
    auth:
      type: basic
      username: api
      password: "{{secrets.api_key}}"
    send:
      method: POST
      url: "https://api.mailgun.net/v3/{{config.domain}}/messages"
      body:
        from: "notifications@{{config.domain}}"
        to: "{{input.recipient}}"
        subject: "{{input.subject}}"
        html: "{{input.html}}"
      response:
        success_status: [200]
        message_id_path: "$.id"

Multi-channel custom providers use a per-channel send map:

providers:
  internal-gateway:
    channels: [email, sms]
    config:
      base_url: { required: true }
      api_key: { required: true, secret: true }
    auth:
      type: bearer
      token: "{{secrets.api_key}}"
    send:
      email:
        method: POST
        url: "{{config.base_url}}/v1/email"
        body:
          to: "{{input.recipient}}"
          subject: "{{input.subject}}"
          html: "{{input.html}}"
      sms:
        method: POST
        url: "{{config.base_url}}/v1/sms"
        body:
          to: "{{input.recipient}}"
          text: "{{input.body}}"

Auth types: bearer (token), basic (username/password), api_key (header or query param with in, key, value).

Config values marked secret: true are resolved from NORQ_<PROVIDER>_<KEY> env vars (uppercased). Non-secret config uses the same convention.

Routing

The routing: section maps channels to providers explicitly. Without explicit routing, Norq uses first-match by registration order (built-ins first, then custom providers in config order).

routing:
  email: mailgun
  sms: internal-gateway
  slack: suprsend
  push: fcm
  push.ios: apns          # platform-scoped routing wins over channel-wide push

Use norq provider routing to inspect the resolved routing table and see which provider handles each channel.

Provider errors

Exit codes