​
Commands Overview

The NOMOS CLI provides powerful commands to bootstrap, develop, and deploy your agents:

nomos init

Create a new agent project interactively

nomos run

Run agent in development mode

nomos train

Interactively refine agent decisions

nomos serve

Deploy agent for production use

nomos test

Run comprehensive agent tests

nomos validate

Validate agent configuration

nomos schema

Export JSON schema for config

nomos --version

Show CLI version information

​
Initialize a New Agent

Create a new agent project with interactive guidance: 
nomos init

​
Options

OptionShortDescriptionDefault
--directory-dProject directory./my-nomos-agent
--name-nAgent nameInteractive prompt
--template-tTemplate (basic, conversational, workflow)Interactive choice
--generate-gGenerate using AIfalse
--usecase-uUse case description for AI generationInteractive prompt
--toolsAvailable tools (comma-separated)Interactive prompt
# Basic interactive setup
nomos init
Walks you through all configuration options step by step.

​
Development Mode

Run your agent locally for development and testing: 
nomos run

​
Options

OptionShortDescriptionDefault
--config-cConfiguration file pathconfig.agent.yaml
--tools-tTool files (can be used multiple times)From config
--verbose-vEnable verbose loggingfalse
# Basic usage
nomos run

# With custom config and verbose logging
nomos run --config my-config.yaml --verbose

# With additional tool files
nomos run --tools custom_tools.py --tools utils.py

​
Training Mode

Interactively improve your agent’s decision-making: 
nomos train
During training:
  1. Agent makes decisions step by step
  2. You provide feedback on unsatisfactory responses
  3. Feedback is stored as examples for future decisions
  4. Agent configuration is updated automatically
Training mode modifies your configuration file. Consider backing it up first.

​
Production Deployment

Serve your agent using FastAPI and Uvicorn: 
nomos serve

​
Options

OptionShortDescriptionDefault
--config-cConfiguration file pathconfig.agent.yaml
--tools-tTool filesFrom config
--port-pServer portFrom config or 8000
--workers-wNumber of workersFrom config or 1
# Basic deployment
nomos serve

# Custom port and workers
nomos serve --port 9000 --workers 4

​
Testing

Run comprehensive tests for your agent: 
nomos test

​
Options

OptionShortDescriptionDefault
--config-cTest configuration filetests.agent.yaml
--coverageGenerate coverage reporttrue
--no-coverageSkip coverage reportfalse
# Run all tests
nomos test

# Custom test config with verbose output
nomos test --config my_tests.yaml -v

# Pass pytest arguments
nomos test tests/test_cli.py -k serve

​
Validate Configuration

New in Latest VersionThe validate command helps ensure your configuration is correct and follows best practices.
Validate your agent configuration for errors and best practices: 
nomos validate config.agent.yaml

​
Options

OptionShortDescription
--verbose-vShow detailed validation information

​
What It Checks

Syntax Validation

YAML syntax, required fields, and data types

Reference Integrity

Step references, route targets, and flow connections

Best Practices

Configuration recommendations and warnings

Field Compatibility

Supports both compact and descriptive field names
# Basic validation
nomos validate config.agent.yaml

# Detailed validation with recommendations
nomos validate config.agent.yaml --verbose

​
Example Output

✓ Configuration is valid!

Configuration Details:
Agent Name: barista
Persona: You are a helpful barista assistant
Number of Steps: 4
Start Step ID: start

Warnings:
• No LLM configuration specified - will use default OpenAI settings

Recommendations:
• Consider adding examples to your steps for better decision-making

​
Generate Schema

Export JSON schema for IDE validation and autocompletion: 
nomos schema --output agent.schema.json
Add to your YAML file for enhanced editing experience: 
# yaml-language-server: $schema=./agent.schema.json
name: my-agent
# ... rest of config

​
Configuration Field Compatibility

Flexible Field NamingNOMOS supports both compact and descriptive field names to accommodate different preferences and migration scenarios.
CompactDescriptiveUsage
idstep_id / flow_idUnique identifiers
descdescriptionDescriptions
toolsavailable_toolsTool lists
pathsroutesStep transitions
totargetRoute targets
whenconditionRoute conditions
egexamplesDecision examples
All examples in documentation use descriptive names, but both formats work identically.

​
Environment Variables

Common environment variables for NOMOS agents:
VariableDescriptionRequired
OPENAI_API_KEYOpenAI API keyIf using OpenAI
MISTRAL_API_KEYMistral API keyIf using Mistral
GOOGLE_API_KEYGoogle API keyIf using Gemini
HUGGINGFACE_API_TOKENHuggingFace tokenIf using HuggingFace

​
Getting Help

For any command, use the --help flag: 
nomos --help
nomos init --help
nomos serve --help