CLI Commands - NeMo Guardrails

The NeMo Guardrails CLI provides a set of commands for interactive testing, server deployment, and configuration management.

Installation

The CLI is automatically installed with NeMo Guardrails:

pip install nemoguardrails

Verify installation:

nemoguardrails --version

Available Commands

View all available commands:

nemoguardrails --help

Output:

Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...

Commands:
  actions-server    Start a NeMo Guardrails actions server.
  chat              Start an interactive chat session.
  eval              Run an evaluation task.
  server            Start a NeMo Guardrails server.
  convert           Convert Colang files from older versions.
  find-providers    List and select LLM providers.

chat

Start an interactive chat session with your guardrails configuration.

Basic Usage

nemoguardrails chat --config=path/to/config

nemoguardrails chat --config=./my_config

Options

--config

string

default:"config"

required

Path to a directory containing configuration files or a single configuration file.

--verbose

boolean

default:"false"

Enable detailed logging information including LLM calls.

--verbose-no-llm

boolean

default:"false"

Enable verbose output but exclude prompts and responses for LLM calls.

--verbose-simplify

boolean

default:"false"

Simplify the verbose output further.

--debug-level

string

Enable debug mode with rich flow execution information. Available levels: WARNING, INFO, DEBUG.

--streaming

boolean

default:"false"

Enable streaming mode for token-by-token responses.

--server-url

string

If specified, the chat CLI will interact with a server instead of loading the config locally.

--config-id

string

The config_id to use when interacting with a server (required with --server-url).

Interactive Commands

When in a chat session, you can use special commands: Colang 2.x Commands:

# Send custom events
/TimerFinished(timer_name="my_timer")
/CustomEvent(param1="value", param2=42)

General Commands:

Press Ctrl+C twice to quit
Press Enter with empty input to check for pending async actions (Colang 2.x)

Examples

Start a basic chat session

nemoguardrails chat --config=./examples/bots/abc

Output:

Starting the chat (Press Ctrl + C twice to quit) ...

> Hello!
Hi! How can I help you?

> What can you do?
I can help answer questions about ABC Company.

Enable verbose mode to see internal processing

nemoguardrails chat --config=./my_config --verbose

Shows:

Canonical form detection
Flow execution
LLM prompts and completions
Rail activations

Test streaming responses

nemoguardrails chat --config=./my_config --streaming

Responses appear token-by-token as they’re generated.

Connect to a remote server

nemoguardrails chat \
  --server-url=http://localhost:8000 \
  --config-id=customer_service

server

Start a NeMo Guardrails REST API server.

Basic Usage

nemoguardrails server --config=path/to/configs

nemoguardrails server --config=./configs

Options

--config

string

default:"./config"

Path to a directory containing multiple configuration sub-folders.

--port

integer

default:"8000"

The port that the server should listen on.

--default-config-id

string

The default configuration to use when no config is specified in requests.

--verbose

boolean

default:"false"

Enable verbose logging including prompts.

--disable-chat-ui

boolean

default:"false"

Disable the web-based Chat UI.

--auto-reload

boolean

default:"false"

Enable automatic reloading when configuration files change.

--prefix

string

default:""

A prefix to add to all server paths (must start with ’/’).

Examples

Start server on custom port

nemoguardrails server --config=./configs --port=9000

Enable auto-reload for development

nemoguardrails server --config=./configs --auto-reload

API-only mode (no UI)

nemoguardrails server --config=./configs --disable-chat-ui

See the Server Guide for detailed information.

eval

Run evaluation tasks on your guardrails configuration.

Basic Usage

nemoguardrails eval --config=path/to/config --eval-type=moderation

The eval command is part of the evaluation framework. See the evaluation documentation for detailed usage.

Common Evaluation Types

nemoguardrails eval \
  --config=./my_config \
  --eval-type=moderation \
  --dataset=./test_data.yaml

actions-server

Start a dedicated actions server for remote action execution.

Basic Usage

nemoguardrails actions-server

nemoguardrails actions-server
# Starts on port 8001

Options

--port

integer

default:"8001"

The port that the actions server should listen on.

Use Case

The actions server allows you to:

Run custom Python actions remotely
Separate action execution from the main guardrails server
Scale action execution independently

Configuration:

config.yml

actions_server_url: http://localhost:8001

convert

Convert Colang files from older versions to the latest version.

Basic Usage

nemoguardrails convert path/to/config

nemoguardrails convert ./old_config --from-version=1.0

Options

path

string

required

The path to the file or directory to migrate.

--from-version

string

default:"1.0"

The version to migrate from. Available: 1.0, 2.0-alpha.

--verbose

boolean

default:"false"

Enable verbose logging.

--validate

boolean

default:"false"

Validate the output using the Colang parser.

--use-active-decorator

boolean

default:"true"

Use the active decorator in the migrated code.

--include-main-flow

boolean

default:"true"

Add a main flow to the migrated configuration.

find-providers

List and interactively select LLM providers.

Basic Usage

nemoguardrails find-providers

nemoguardrails find-providers
# Opens interactive prompt to select provider type and provider

Options

--list

boolean

default:"false"

Just list all available providers without interactive selection.

Interactive Mode

When run without --list, the command provides an interactive interface:

Select provider type: Type to filter between “text completion” and “chat completion”
Select provider: Type to filter through available providers
Navigate: Use arrow keys to navigate, Tab to autocomplete, Enter to select

Common Workflows

Development Workflow

Test configuration locally

nemoguardrails chat --config=./my_config --verbose

Start server with auto-reload

nemoguardrails server --config=./my_config --auto-reload

Iterate on configuration files

Edit .co files and config.yml - changes reload automatically

Test with streaming

nemoguardrails chat --config=./my_config --streaming

Testing Workflow

Run evaluation suite

nemoguardrails eval --config=./my_config --dataset=./tests.yaml

Test with verbose logging

nemoguardrails chat --config=./my_config --verbose --debug-level=INFO

Verify against remote server

nemoguardrails chat --server-url=http://localhost:8000 --config-id=my_config

Deployment Workflow

Validate configuration

nemoguardrails chat --config=./production_config
# Test interactively first

Start production server

nemoguardrails server \
  --config=./production_config \
  --port=8000 \
  --disable-chat-ui

Monitor with verbose logs

nemoguardrails server \
  --config=./production_config \
  --verbose

Environment Variables

The CLI respects standard environment variables:

# LLM API keys
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# Model configuration
export MAIN_MODEL_ENGINE=openai
export MAIN_MODEL_BASE_URL=http://localhost:8080/v1

# Server configuration
export NEMO_GUARDRAILS_SERVER_ENABLE_CORS=true
export NEMO_GUARDRAILS_SERVER_ALLOWED_ORIGINS="*"

# Tokenization
export TOKENIZERS_PARALLELISM=false

# Debug
export DEBUG_MODE=1

Troubleshooting

Command Not Found

Ensure NeMo Guardrails is installed:

pip install nemoguardrails
# Or
pip install nemoguardrails[server]  # With server dependencies

Configuration Not Loading

Verify the path exists and contains valid files:

ls -la path/to/config/
# Should show config.yml and .co files

Streaming Not Working

Enable streaming in configuration:

config.yml

rails:
  output:
    streaming:
      enabled: true

Port Already in Use

Change the port:

nemoguardrails server --config=./configs --port=8080

Next Steps

Python API

Use guardrails programmatically

Server Guide

Deploy guardrails as a REST API

Configuration

Configure your guardrails

Evaluation

Test and evaluate your guardrails

Get Started

Core Concepts

Configuration

Guardrails Library

Built-in Guardrails

Usage

Deployment

Evaluation

​Installation

​Available Commands

​chat

​Basic Usage

​Options

​Interactive Commands

​Examples

​server

​Basic Usage

​Options

​Examples

​eval

​Basic Usage

​Common Evaluation Types

​actions-server

​Basic Usage

​Options

​Use Case

​convert

​Basic Usage

​Options

​find-providers

​Basic Usage

​Options

​Interactive Mode

​Common Workflows

​Development Workflow

​Testing Workflow

​Deployment Workflow

​Environment Variables

​Troubleshooting

​Command Not Found

​Configuration Not Loading

​Streaming Not Working

​Port Already in Use

​Next Steps

Python API

Server Guide

Configuration

Evaluation

Build docs developers (and LLMs) love

Installation

Available Commands

chat

Basic Usage

Options

Interactive Commands

Examples

server

Basic Usage

Options

Examples

eval

Basic Usage

Common Evaluation Types

actions-server

Basic Usage

Options

Use Case

convert

Basic Usage

Options

find-providers

Basic Usage

Options

Interactive Mode

Common Workflows

Development Workflow

Testing Workflow

Deployment Workflow

Environment Variables

Troubleshooting

Command Not Found

Configuration Not Loading

Streaming Not Working

Port Already in Use

Next Steps