CLI

The Norn CLI runs .norn tests and .nornk8s runbooks from the terminal. Use it for local checks, CI pipelines, named requests, Kubernetes operations, and report generation.

Installation

Install the published CLI package globally via npm:

shell 
npm install -g norn-cli

Usage

shell 
norn <file.norn|file.nornk8s|directory> [options]

When you pass a directory, Norn recursively discovers .norn and .nornk8s files. It runs test sequence blocks from .norn files and runbook sequence blocks from .nornk8s files.

Basic Commands

shell 
# Run all test sequences in a file
norn api-tests.norn

# Run all test sequences in a directory
norn tests/

# Run one sequence by name
norn api-tests.norn --sequence AuthFlow

# Run one named request by name
norn api-tests.norn --request LoginRequest

Kubernetes Runbooks

Direct .nornk8s runs execute every runbook sequence entry point. Use --sequence to run one helper or runbook sequence, --context to select a cluster, and --yes when the run can restart a deployment.

shell 
# Run automatic runbook entries
norn runbooks/triage.nornk8s --context prelive

# Run one helper sequence
norn runbooks/triage.nornk8s -s Triage --context prelive

# Allow a deployment restart
norn runbooks/triage.nornk8s -s RestartOrders --context prelive --yes

Kubernetes commands keep finite raw kubectl output in the CLI. JUnit and HTML reports are not supported for .nornk8s files, and --json is not supported for directory runs that contain them. See Kubernetes & Norn Terminal for syntax, context precedence, and safety details.

Shared Runtime Features

The CLI runs the same shared runtime as the VS Code extension. Files that use run sql or run mcp behave the same way in terminal runs as they do in editor runs.

shell 
# Run a file that includes MCP steps
norn smoke-mcp.norn --sequence TimeTools --env prelive

# Run a suite that includes SQL, scripts, HTTP, and MCP steps
norn tests/ --env prelive

Request Timeouts

HTTP requests use a 30 second timeout by default. Teams can set a shared timeout in norn.config.json, and CI can override it for a single run with --timeout.

norn.config.json 
{
  "version": 1,
  "http": {
    "timeoutMs": 180000
  }
}
shell 
# Override the project timeout for this run
norn tests/ --timeout 180s
norn tests/ --timeout 3m
norn tests/ --timeout 300000ms

The CLI accepts ms, s, and m suffixes. Bare numbers are treated as seconds for command-line compatibility. Precedence is --timeout, then norn.config.json, then the built-in 30 second default.

Environment Selection

shell 
norn tests/ --env staging
norn tests/ -e production

Environment File Refactors

The CLI can print or apply the same stage/region .nornenv refactor that appears in VS Code. Use it when a file has flat environment names such as dev_us, dev_uk, prod_us, and prod_uk.

shell 
# Preview the refactored .nornenv content
norn .nornenv --refactor-region-pattern

# Rewrite the file in place
norn .nornenv --refactor-region-pattern --write

Tag Filtering

--tag uses AND logic when repeated. --tags uses OR logic for a comma-separated list.

shell 
# Single tag
norn tests/ --tag smoke

# All listed tags must match (AND)
norn tests/ --tag smoke --tag critical

# Any listed tag may match (OR)
norn tests/ --tags smoke,critical

# Key-value tag
norn tests/ --tag "team(CustomerExp)"

Reports

Use explicit file paths when you want one report, or --output-dir to auto-generate timestamped report names.

shell 
# Explicit report files
norn tests/ --junit results/junit.xml
norn tests/ --html results/report.html

# Auto-generated report filenames
norn tests/ --output-dir results

Output and Diagnostics

Contract assertions are summarized by schema name in terminal output, including validation counts and the first issues when a schema check fails.

text 
✓ GET-todos-1.schema.json: 4/4 validations passed
shell 
norn tests/ --json
norn tests/ --verbose
norn tests/ --timeout 180s
norn tests/ --no-fail
norn tests/ --no-redact
norn api-tests.norn --insecure

CI/CD Example

GitHub Actions

workflow.yml 
name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      
      - name: Install Norn CLI
        run: npm install -g norn-cli
      
      - name: Prepare report folder
        run: mkdir -p results
      
      - name: Run Tests
        run: norn tests/ --env ci --junit results/junit.xml
      
      - name: Upload Results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results/

Exit Codes

  • 0 - Run completed successfully
  • 1 - A test failed, a request failed, or Norn hit a configuration/runtime error