Command Reference

This is the complete reference for all Codebolt CLI commands. Each command includes syntax, options, examples, and usage notes.

Global Options

All commands support these global options:

--help, -h      Show help information
--version, -v   Show version information

Authentication Commands

`login`

Authenticate with your Codebolt account.

codebolt-cli login

Description: Initiates the login process with interactive prompts for email and password.

Interactive Flow:

Prompts for email address
Prompts for password (hidden input)
Stores authentication token securely
Confirms successful login

Examples:

# Basic login
codebolt-cli login

# Example output
? Email: [email protected]
? Password: [hidden]
✓ Successfully logged in!

Related Commands: logout

`logout`

End your current session.

codebolt-cli logout

Description: Clears stored authentication data and ends the current session.

Examples:

codebolt-cli logout
# Output: Successfully logged out!

Related Commands: login

Agent Commands

`createagent`

Create a new Codebolt agent.

codebolt-cli createagent [options]

Options:

-n, --name <name> - Name of the agent
--quick - Create agent with default settings

Description: Creates a new agent with interactive configuration or quick setup.

Interactive Mode:

Basic Information (name, description, unique ID, tags)
Agent Routing (languages, frameworks, compatibility)
SDLC Steps (development phases managed)
Actions (shortcut commands)

Examples:

# Interactive creation
codebolt-cli createagent

# Quick creation with name
codebolt-cli createagent --name "My Agent" --quick

# Named creation (still interactive for other options)
codebolt-cli createagent --name "React Generator"

Output: Creates agent directory in .codeboltAgents/agents/

Related Commands: publishagent, startagent

`publishagent`

Publish an agent to the Codebolt platform.

codebolt-cli publishagent [folderPath]

Parameters:

folderPath (optional) - Path to agent directory (defaults to current directory)

Description: Validates, packages, and uploads an agent to make it available on the platform.

Requirements:

Valid codeboltagent.yaml configuration
Authentication (must be logged in)
All required files present

Examples:

# Publish from current directory
codebolt-cli publishagent

# Publish specific agent
codebolt-cli publishagent ./my-agent

# Publish from agents directory
codebolt-cli publishagent ./.codeboltAgents/agents/my-agent

Process:

Validates agent configuration
Packages agent files
Uploads to platform
Returns publication status

Related Commands: createagent, listagents

`listagents`

List all your published agents.

codebolt-cli listagents

Description: Displays all agents you've created and published to the platform.

Requirements: Authentication (must be logged in)

Output Format:

Agent name and description
Unique identifier
Publication status
Last update timestamp
Tags and metadata

Examples:

codebolt-cli listagents

# Example output
┌─────────────────────┬──────────────────────┬─────────────────┬─────────────┐
│ Name                │ Description          │ Unique ID       │ Updated     │
├─────────────────────┼──────────────────────┼─────────────────┼─────────────┤
│ React Generator     │ Creates React comps  │ react-gen       │ 2 days ago  │
│ API Builder         │ Builds REST APIs     │ api-builder     │ 1 week ago  │
└─────────────────────┴──────────────────────┴─────────────────┴─────────────┘

Related Commands: publishagent, cloneagent

`startagent`

Start an agent in a working directory.

codebolt-cli startagent [workingDir]

Parameters:

workingDir (optional) - Directory to start agent in (defaults to current directory)

Description: Starts an agent locally for development and testing.

Requirements:

Valid agent directory with codeboltagent.yaml
Node.js dependencies installed

Examples:

# Start in current directory
codebolt-cli startagent

# Start in specific directory
codebolt-cli startagent ./my-agent

# Start with specific working directory
codebolt-cli startagent ./.codeboltAgents/agents/my-agent

Related Commands: createagent, pullagent

`pullagent`

Pull the latest agent configuration from the server.

codebolt-cli pullagent [workingDir]

Parameters:

workingDir (optional) - Directory to pull agent to (defaults to current directory)

Description: Synchronizes local agent with the latest version from the platform.

Requirements: Authentication (must be logged in)

Examples:

# Pull to current directory
codebolt-cli pullagent

# Pull to specific directory
codebolt-cli pullagent ./my-agent

Process:

Identifies agent from local configuration
Downloads latest version from platform
Updates local files
Preserves local modifications where possible

Related Commands: publishagent, startagent

`cloneagent`

Clone an existing agent using its unique identifier.

codebolt-cli cloneagent <unique_id> [targetDir]

Parameters:

unique_id (required) - Unique identifier of the agent to clone
targetDir (optional) - Target directory (defaults to current directory)

Description: Downloads and creates a local copy of an existing agent for customization.

Examples:

# Clone to current directory
codebolt-cli cloneagent react-component-generator

# Clone to specific directory
codebolt-cli cloneagent react-component-generator ./my-custom-agent

# Clone to agents directory
codebolt-cli cloneagent api-builder ./.codeboltAgents/agents/my-api-builder

Output: Creates complete agent directory with all files and configuration.

Related Commands: listagents, createagent

Tool Commands

`createtool`

Create a new Codebolt tool.

codebolt-cli createtool [options]

Options:

-n, --name <name> - Tool display name
-i, --id <unique-id> - Unique identifier (no spaces, lowercase)
-d, --description <description> - Tool description
-p, --parameters <json> - Tool parameters in JSON format

Description: Creates a new tool with MCP compatibility.

Examples:

# Interactive creation
codebolt-cli createtool

# With all options
codebolt-cli createtool \
  --name "File Manager" \
  --id "file-manager" \
  --description "Manages file operations" \
  --parameters '{"rootPath": "./", "extensions": [".js", ".ts"]}'

# Partial options (prompts for missing)
codebolt-cli createtool --name "Database Tool" --id "db-tool"

Validation:

Unique ID cannot contain spaces
Parameters must be valid JSON
ID is automatically converted to lowercase

Output: Creates tool directory in .codeboltAgents/tools/

Related Commands: runtool, inspecttool

`runtool`

Run a tool with a specific command.

codebolt-cli runtool <command> <file>

Parameters:

command (required) - Tool command to execute
file (required) - Path to tool file

Description: Executes a specific tool command for testing and development.

Examples:

# Run list_files command
codebolt-cli runtool list_files ./my-tool/index.js

# Run read_file command
codebolt-cli runtool read_file ./my-tool/index.js

# Run custom command
codebolt-cli runtool process_data ./my-tool/index.js

Requirements:

Valid tool implementation
Tool must export the specified command handler

Related Commands: createtool, inspecttool

`inspecttool`

Inspect a tool using the MCP inspector.

codebolt-cli inspecttool <file>

Parameters:

file (required) - Path to tool file

Description: Opens an interactive MCP inspector for debugging and testing tools.

Features:

Interactive command testing
Parameter inspection
Response debugging
Performance monitoring

Examples:

# Inspect tool
codebolt-cli inspecttool ./my-tool/index.js

# Inspect with specific configuration
codebolt-cli inspecttool ./.codeboltAgents/tools/file-manager/index.js

Requirements:

Tool must be MCP-compatible
Node.js environment

Related Commands: createtool, runtool

Utility Commands

`version`

Display the CLI version.

codebolt-cli version

Description: Shows the current version of the Codebolt CLI.

Examples:

codebolt-cli version
# Output: Codebolt CLI version 1.1.35

Command Patterns

Directory Structure Commands

Commands that work with the .codeboltAgents directory structure:

your-project/
├── .codeboltAgents/
│   ├── agents/
│   │   ├── agent-1/
│   │   └── agent-2/
│   └── tools/
│       ├── tool-1/
│       └── tool-2/
└── your-files...

Affected Commands:

createagent - Creates in .codeboltAgents/agents/
createtool - Creates in .codeboltAgents/tools/
startagent - Looks for agents in current or specified directory
cloneagent - Can target any directory

Authentication Required

Commands that require login:

publishagent - Upload agents to platform
listagents - List your published agents
pullagent - Sync with platform
cloneagent - Access to private agents

Local Development

Commands that work offline:

createagent - Create local agents
createtool - Create local tools
startagent - Run agents locally
runtool - Test tools locally
inspecttool - Debug tools locally
version - Show CLI version

Error Handling

Common Error Patterns

Authentication Errors

Error: Not authenticated. Please run 'codebolt-cli login' first.

Solution: Run codebolt-cli login

File Not Found

Error: Agent configuration not found in current directory.

Solution: Ensure you're in the correct directory or specify the path

Validation Errors

Error: Invalid codeboltagent.yaml format

Solution: Check YAML syntax and required fields

Network Errors

Error: Unable to connect to Codebolt platform

Solution: Check internet connection and try again

Debug Mode

Enable verbose logging for troubleshooting:

DEBUG=codebolt:* codebolt-cli <command>

Configuration Files

Agent Configuration (`codeboltagent.yaml`)

Required for agent commands:

title: "Agent Name"
description: "Agent description"
unique_id: "agent-unique-id"
tags: ["tag1", "tag2"]
version: "1.0.0"

metadata:
  agent_routing:
    worksonblankcode: true
    worksonexistingcode: true
    supportedlanguages: ["javascript"]
    supportedframeworks: ["react"]
  
  sdlc_steps_managed:
    - name: "Code Generation"
      example_instructions: ["Generate component"]

actions:
  - name: "action-name"
    description: "Action description"

Tool Configuration (`codebolttool.yaml`)

Required for tool commands:

name: "Tool Name"
description: "Tool description"
version: "1.0.0"
uniqueName: "tool-unique-name"

parameters:
  param1:
    type: "string"
    description: "Parameter description"
    default: "default-value"

Best Practices

Command Usage

Always authenticate first for platform operations
Use descriptive names for agents and tools
Test locally before publishing
Keep unique IDs consistent across environments
Use version control for your agents and tools

Directory Organization

# Recommended project structure
your-project/
├── .codeboltAgents/
│   ├── agents/
│   │   └── my-agent/
│   └── tools/
│       └── my-tool/
├── src/
├── package.json
└── README.md

Development Workflow

Create agent/tool locally
Test with startagent/runtool
Debug with inspecttool if needed
Publish when ready
List to verify publication
Pull to sync updates

Examples

Complete Agent Workflow

# 1. Create agent
codebolt-cli createagent --name "My Agent"

# 2. Test locally
codebolt-cli startagent ./.codeboltAgents/agents/my-agent

# 3. Publish
codebolt-cli publishagent ./.codeboltAgents/agents/my-agent

# 4. Verify
codebolt-cli listagents

Complete Tool Workflow

# 1. Create tool
codebolt-cli createtool --name "My Tool" --id "my-tool"

# 2. Test command
codebolt-cli runtool test_command ./.codeboltAgents/tools/my-tool/index.js

# 3. Debug if needed
codebolt-cli inspecttool ./.codeboltAgents/tools/my-tool/index.js

Multi-Agent Project

# Create multiple agents
codebolt-cli createagent --name "Frontend Agent"
codebolt-cli createagent --name "Backend Agent"
codebolt-cli createagent --name "Database Agent"

# Create shared tools
codebolt-cli createtool --name "File Utils" --id "file-utils"
codebolt-cli createtool --name "API Client" --id "api-client"

# Publish all
codebolt-cli publishagent ./.codeboltAgents/agents/frontend-agent
codebolt-cli publishagent ./.codeboltAgents/agents/backend-agent
codebolt-cli publishagent ./.codeboltAgents/agents/database-agent

Global Options​

Authentication Commands​

login​

logout​

Agent Commands​

createagent​

publishagent​

listagents​

startagent​

pullagent​

cloneagent​

Tool Commands​

createtool​

runtool​

inspecttool​

Utility Commands​

version​

Command Patterns​

Directory Structure Commands​

Authentication Required​

Local Development​

Error Handling​

Common Error Patterns​

Authentication Errors​

File Not Found​

Validation Errors​

Network Errors​

Debug Mode​

Configuration Files​

Agent Configuration (codeboltagent.yaml)​

Tool Configuration (codebolttool.yaml)​

Best Practices​

Command Usage​

Directory Organization​

Development Workflow​

Examples​

Complete Agent Workflow​

Complete Tool Workflow​

Multi-Agent Project​

Global Options

Authentication Commands

`login`

`logout`

Agent Commands

`createagent`

`publishagent`

`listagents`

`startagent`

`pullagent`

`cloneagent`

Tool Commands

`createtool`

`runtool`

`inspecttool`

Utility Commands

`version`

Command Patterns

Directory Structure Commands

Authentication Required

Local Development

Error Handling

Common Error Patterns

Authentication Errors

File Not Found

Validation Errors

Network Errors

Debug Mode

Configuration Files

Agent Configuration (`codeboltagent.yaml`)

Tool Configuration (`codebolttool.yaml`)

Best Practices

Command Usage

Directory Organization

Development Workflow

Examples

Complete Agent Workflow

Complete Tool Workflow

Multi-Agent Project