Skip to navigation

NeMo Guardrails Library CLI Reference

View as MarkdownOpen in Claude

NeMo Guardrails Library CLI Reference

You should now be able to invoke the nemoguardrails CLI.

> nemoguardrails --help
Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...
Options:
-v, --version Show version and exit.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it
or customize the installation.
--help Show this message and exit.
Commands:
chat Start an interactive chat session.
server Start a NeMo Guardrails server.
hooks-server Start a NeMo Guardrails hooks server, which checks
agents' tool calls before they run.
convert Convert Colang files and configs from older version to
the latest.
actions-server Start a NeMo Guardrails actions server.
find-providers List and select LLM providers interactively.
eval Evaluation a guardrail configuration.

You can also use the --help flag to learn more about each of the nemoguardrails commands.


chat

Chat with a Colang 2.x configuration, including its debugger commands, is deprecated in 0.25.0; removal is planned no earlier than 0.27.0. nemoguardrails chat prints this notice to standard error when it loads a Colang 2.x configuration. For the steps, refer to Migrating to 0.25.

nemoguardrails chat --config examples/configs/content_safety [--verbose] [--streaming]

Options

OptionDescription
--configPath to a directory containing configuration files. Can also point to a single configuration file. Default: config.
--verboseEnable verbose mode with detailed logging information.
--verbose-no-llmEnable verbose mode but exclude LLM prompts and responses.
--verbose-simplifySimplify the verbose output.
--debug-levelEnable debug mode with rich flow execution info. Levels: WARNING, INFO, DEBUG.
--streamingEnable streaming mode if the configuration supports it.
--server-urlConnect to a server instead of loading config locally. Requires --config-id.
--config-idThe config ID to use when connecting to a server.

actions-server

Start a separate server process for running custom actions. Process separation does not sandbox action code or restrict its filesystem and network access.

nemoguardrails actions-server --port 8001

Options

OptionDescription
--portThe port that the server should listen on. Default: 8001.

server

Start the FastAPI server for serving guardrails configurations over HTTP.

nemoguardrails server --config examples/configs --port 8000

Options

OptionDescription
--portThe port that the server should listen on. Default: 8000.
--configPath to a directory containing multiple configuration sub-folders.
--default-config-idThe default configuration to use when no config is specified in requests.
--verboseEnable verbose mode with detailed logs including prompts.
--disable-chat-uiDisable the Chat UI served at the root path.
--auto-reloadEnable auto reload when configuration files change.
--prefixA prefix to add to all server paths. Must start with /.
--metrics-exporterExpose the IORails non-streaming admission-queue metrics (guardrails.nonstream.*) on a scrape endpoint. Supported values: prometheus and none. Use none to disable export. Overrides NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER. Default: none.
--metrics-hostInterface for the Prometheus scrape endpoint. Overrides NEMO_GUARDRAILS_SERVER_METRICS_HOST. Default: 0.0.0.0.
--metrics-portPort for the Prometheus scrape endpoint. Overrides NEMO_GUARDRAILS_SERVER_METRICS_PORT. Default: 9464.

hooks-server

Start the Guardrails hooks server, which checks coding agents’ tool calls from their pre-tool hooks. It is a separate server from server, with its own endpoints and defaults. For details, refer to Run the Hooks Server.

nemoguardrails hooks-server --config examples/configs/agent_hooks/claude_code --port 8100

Options

OptionDescription
--configPath to the configuration directory or file. Required, exactly once.
--hostThe interface to listen on. Default: 127.0.0.1. The server has no authentication, so the default is loopback only.
--portThe port the server listens on. Default: 8100.
--metrics-exporterExpose the IORails non-streaming admission-queue metrics (guardrails.nonstream.*) on a scrape endpoint. Supported values: prometheus and none. Overrides NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER. Default: none.
--metrics-hostInterface for the Prometheus scrape endpoint. Overrides NEMO_GUARDRAILS_SERVER_METRICS_HOST. Default: 127.0.0.1.
--metrics-portPort for the Prometheus scrape endpoint. Overrides NEMO_GUARDRAILS_SERVER_METRICS_PORT. Default: 9465.

eval

Evaluate guardrail configurations with various testing and compliance workflows. The following example runs the interactions in the sample ABC evaluation configuration (-e) through the ABC bot guardrails configuration (-g):

nemoguardrails eval run -e examples/eval/sample_abc/config -g examples/bots/abc

Subcommands

SubcommandDescription
runRun the interactions for an evaluation.
check-complianceCheck the policy compliance of the interactions in the output path.
uiLaunch the Evaluation UI.
railRun a rail evaluation task: topical, fact-checking, moderation, or hallucination. For details, refer to Evaluate Guardrails.

Use nemoguardrails eval <subcommand> --help for details on each subcommand.


convert

Convert Colang files and configurations from older versions to the latest format.

nemoguardrails convert ./my-config --from-version 1.0 --validate

Arguments

ArgumentDescription
PATHThe path to the file or directory to migrate. Required.

Options

OptionDescription
--from-versionThe version of the Colang files to migrate from. Options: 1.0, 2.0-alpha. Default: 1.0.
--verboseEnable verbose mode with detailed logs.
--validateValidate the output using the Colang Parser.
--use-active-decoratorUse the active decorator in the migration. Default: enabled.
--include-main-flowAdd a main flow to the config. Default: enabled.

find-providers

List and select LLM providers interactively. This command helps you discover available providers for text completion and chat completion models.

nemoguardrails find-providers --list

Options

OptionDescription
--list, -lList all available providers without interactive selection.

List Mode

Run the following command to list all available providers:

nemoguardrails find-providers --list

Interactive Mode

Run the command without options to start an interactive provider selection:

nemoguardrails find-providers
  1. Select a provider type:

    • Type to filter between “text completion” and “chat completion”.
    • Use arrow keys to navigate through matches.
    • Press Tab to autocomplete.
    • Press Enter to select.
  2. Select a specific provider:

    • Type to filter through available providers.
    • Use arrow keys to navigate through matches.
    • Press Tab to autocomplete.
    • Press Enter to select.

Example

Available Provider Types: (type to filter, use arrows to select)
• text completion
• chat completion
Select provider type: text
Available text completion providers: (type to filter, use arrows to select)
• anthropic
• google_palm
• openai
• ...
Select provider: openai
Selected text completion provider: openai