CLI

The Norn CLI runs .norn files and test suites from the terminal. Use it for local checks, CI pipelines, named requests, and report generation.

Installation

Install the published CLI package globally via npm:

shell 
npm install -g norn-cli

Usage

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

When you pass a directory, Norn recursively discovers .norn files and runs their test sequence blocks.

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

Environment Selection

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

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

shell 
norn tests/ --json
norn tests/ --verbose
norn tests/ --timeout 30
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