CLI Commands

Command-line interface tools for testing, development, and deployment

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

Basic Chat

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:

Events

# 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

1. 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.
   
2. 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
3. Test streaming responses

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

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

4. 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

Basic Server

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

Moderation

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

Default Port

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

Convert from 1.0

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

Interactive Selection

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:

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

Common Workflows

Development Workflow

1. Test configuration locally

   nemoguardrails chat --config=./my_config --verbose
   
2. Start server with auto-reload

   nemoguardrails server --config=./my_config --auto-reload
   
3. Iterate on configuration files

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

4. Test with streaming

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

Testing Workflow

1. Run evaluation suite

   nemoguardrails eval --config=./my_config --dataset=./tests.yaml
   
2. Test with verbose logging

   nemoguardrails chat --config=./my_config --verbose --debug-level=INFO
   
3. Verify against remote server

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

Deployment Workflow

1. Validate configuration

   nemoguardrails chat --config=./production_config
   # Test interactively first
   
2. Start production server

   nemoguardrails server \
     --config=./production_config \
     --port=8000 \
     --disable-chat-ui
   
3. 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