CLI Commands

Carnet provides a command-line interface for managing your agent content and building the final manifest. This guide covers the available commands,

Key Features

• No Config Required - Works with built-in defaults immediately
• Config File Optional - Use carnet.config.json for persistent settings
• Full CLI Control - All configuration options available as CLI flags
• Configuration Precedence - CLI options override config file and environment variables
• Repeatable Options - Use options multiple times: --variables KEY=VALUE --variables KEY2=VALUE2

Global Options

All commands support these global options:

carnet [command] [options]

Available globally:

• -d, --dir <dir> - Carnet project directory containing carnet.config.json and content (default: ./carnet)

Configuration Precedence

When you specify the same setting in multiple ways, Carnet uses this priority order:

1. CLI options (highest priority) - What you type on the command line
2. Environment variables (e.g., CARNET_OUTPUT=./build)
3. Config file (carnet.config.json)
4. Schema defaults (lowest priority) - Built-in sensible defaults

Example:

# Config file says: output: "./dist"
# But CLI option wins:
carnet build --output ./build   # Uses ./build (CLI wins)

# Environment variable overrides config but not CLI:
CARNET_OUTPUT=./app carnet build        # Uses ./app (env var)
CARNET_OUTPUT=./app carnet build --output ./custom  # Uses ./custom (CLI wins)

Available Commands

Command	Purpose
init	Initialize a new Carnet project
build	Build markdown files into manifest
lint	Lint content without building
list	Display agents in tree format
show	Display entity details

Quick Reference

Initialize a Project

carnet init my-project

Build Your Content

Without config file (CLI-only):

# Uses defaults: ./carnet → ./dist
carnet build

# Override with CLI options
carnet build --output ./build --variables API_KEY=secret

With config file:

carnet build
carnet build --watch         # Watch for changes
carnet build -o ./output     # Custom output directory

Lint Content

Without config file:

carnet lint

With options:

carnet lint --exclude "**/draft/**"
carnet lint --variables ENV=prod

List Agents

carnet list
carnet list my-agent         # Show specific agent

Show Details

carnet show agent my-agent
carnet show skill my-skill
carnet show toolset my-toolset
carnet show tool my-tool

Common Workflows

Development Workflow

# Watch for changes during development
carnet build --watch

CI/CD Integration

# Lint before building
carnet lint || exit 1

# Build for deployment
carnet build --output ./dist

# Verify structure
carnet list

Production Build

# Build for deployment
carnet build --output ./dist

# Lint the output
carnet lint

Help & Documentation

Get help for any command:

carnet --help                    # Show all commands
carnet build --help              # Show build command help
carnet --version                 # Show version

Next Steps

• Detailed command reference
• Configuration options
• API reference
• Quick start guide