CLI Reference

Complete reference for all Gentoro OneMCP CLI commands, configuration files, and options.

Command Overview

onemcp [command] [options]

Quick Reference

Global Flags

Available for all commands:

• --config string - Config file (default: ~/.onemcp/config.yaml)
• -h, --help - Help for any command

Core Commands

chat

Open interactive chat mode with MCP server.

Usage:

onemcp chat

Behavior:

• Starts Docker container if not running
• Waits for server to be ready
• Opens interactive chat session
• Displays ACME example prompts (if using acme-analytics)

In-Chat Commands:

Example:

onemcp chat
 
# Output:
# ╔══════════════════════════════════════╗
# ║    Gentoro OneMCP - Chat Mode        ║
# ╚══════════════════════════════════════╝
#
# Handbook: acme-analytics
# Provider: gemini
#
# You: Show total sales for 2024
# Agent: {...}

status

Show OneMCP server and configuration status.

Usage:

onemcp status

Output:

• Docker container status
• Server health
• Current handbook
• Active AI provider
• Configuration file path

Example:

onemcp status
 
# Output:
# Docker container: running
# Server health: healthy
# Current handbook: acme-analytics
# Active provider: gemini
# Config: /Users/you/.onemcp/config.yaml

stop

Stop the OneMCP server.

Usage:

onemcp stop

Behavior:

• Gracefully stops Docker container
• Preserves configuration and logs

Example:

onemcp stop
 
# Output:
# Stopping OneMCP server...
# Container stopped

logs

View OneMCP server logs.

Usage:

onemcp logs [flags]

Flags:

• -n, --lines int - Number of lines to show (default: 50)
• -f, --follow - Follow log output in real-time

Examples:

# Show last 50 lines
onemcp logs
 
# Show last 100 lines
onemcp logs -n 100
 
# Follow logs in real-time
onemcp logs -f
 
# Follow last 200 lines
onemcp logs -n 200 -f

Use Cases:

• Debugging connection issues
• Monitoring server performance
• Viewing API call traces
• Troubleshooting errors

doctor

Check system requirements and configuration.

Usage:

onemcp doctor

Checks:

• Docker installed
• Docker daemon running
• Network connectivity
• Configuration file validity
• Required permissions

Example:

onemcp doctor
 
# Output:
# ✓ Docker is installed
# ✓ Docker daemon is running
# ✓ Network connectivity OK
# ✓ Configuration file valid
# ✓ All requirements met

update

Update OneMCP Docker image and display CLI update instructions.

Usage:

onemcp update

Behavior:

• Detects installation method (Homebrew, Scoop, or Manual)
• Displays appropriate update instructions for the CLI binary
• Pulls latest admingentoro/gentoro:latest Docker image

Example:

onemcp update
 
# Output:
# 📌 To update the OneMCP CLI:
#
#   Homebrew:
#     brew upgrade onemcp
#
# 📦 Updating OneMCP Docker image...
# latest: Pulling from admin gent oro/gentoro
# Digest: sha256:...
# ✅ Docker image updated successfully!

Installation Detection:

The command automatically detects how the CLI was installed:

• Homebrew: Checks for Cellar path or brew list onemcp
• Scoop: Checks for Scoop apps path or scoop list onemcp
• Manual: Falls back if neither package manager is detected

Note: This command only updates the Docker image. To update the CLI binary itself, use your package manager or download manually.

version

Show the OneMCP CLI version.

Usage:

onemcp version
# or
onemcp --version

Example:

onemcp version
 
# Output:
# OneMCP CLI v0.0.3

Note: Version is set at build time via ldflags during the release process.

reset

Reset all OneMCP configuration.

Usage:

onemcp reset

Warning: This deletes all configuration files. Handbooks are preserved.

What gets deleted:

• ~/.onemcp/config.yaml
• All provider configurations
• All cached data

What is preserved:

• Handbooks in ~/onemcp-handbooks/
• Service authentication files

Example:

onemcp reset
 
# Output:
# ⚠️  This will delete all configuration.
# Handbooks will be preserved.
# Continue? (y/N): y
# Configuration reset successfully

Provider Management

provider set

Configure an AI provider and API key.

Usage:

onemcp provider set

Interactive Prompts:

1. Select provider (OpenAI, Google Gemini, Anthropic)
2. Enter API key
3. Configuration saved

Supported Providers:

• OpenAI - GPT-4, GPT-3.5-turbo
• Google Gemini - Gemini Pro, Gemini Flash
• Anthropic - Claude 3 Opus, Sonnet, Haiku

Example:

onemcp provider set
 
# Interactive:
# ? Select AI provider: Google Gemini
# ? Enter your Gemini API key: **********************
# ✓ Provider configured successfully

provider list

Show all configured AI providers.

Usage:

onemcp provider list

Output:

• Provider name
• Masked API key (first 6 and last 3 chars)
• Current provider indicator

Example:

onemcp provider list
 
# Output:
# Configured Providers:
#   ✓ gemini: AIza************************ (active)
#   ✓ openai: sk-proj-********************
#   - anthropic: (not configured)

provider switch

Switch between configured providers.

Usage:

onemcp provider switch

Interactive Prompts:

• Shows list of configured providers
• Select provider to activate
• No need to re-enter API keys

Example:

onemcp provider switch
 
# Interactive:
# ? Select provider to use:
#   > gemini (AIza...abc) [current]
#     openai (sk-proj...xyz)
#     anthropic (sk-ant...123)

Handbook Management

handbook init

Create a new handbook.

Usage:

onemcp handbook init <name>

Arguments:

• name (required) - Name for the new handbook

Behavior:

• Creates handbook directory at ~/onemcp-handbooks/<name>
• Generates template files
• Creates standard directory structure

Directory Structure Created:

~/onemcp-handbooks/<name>/
├── Agent.yaml              # AI instructions template
├── README.md             # Handbook overview template
├── getting-started.md    # Quick start template
└── openapi/              # OpenAPI specs directory
    └── README.md         # Instructions for adding specs

Example:

onemcp handbook init customer-api
 
# Output:
# ✓ Created handbook: customer-api
# ✓ Directory: ~/onemcp-handbooks/customer-api
# 
# Next steps:
#   1. Add OpenAPI spec to openapi/ directory
#   2. Customize Agent.yaml with instructions
#   3. Run: onemcp handbook validate customer-api

handbook list

List all available handbooks.

Usage:

onemcp handbook list

Output:

• Handbook name
• Location (built-in or custom)
• Current handbook indicator

Example:

onemcp handbook list
 
# Output:
# Available Handbooks:
#   - acme-analytics (built-in)
#   * customer-api (current)
#   - analytics-service
#   - payment-api

handbook use

Set the active handbook.

Usage:

onemcp handbook use [name]

Arguments:

• name (optional) - Handbook to activate. If omitted, shows interactive selection.

Behavior:

• Updates currenthandbook in ~/.onemcp/config.yaml
• Subsequent onemcp chat commands use this handbook

Examples:

# Interactive selection
onemcp handbook use
 
# Direct selection
onemcp handbook use customer-api
 
# Output:
# ✓ Switched to handbook: customer-api

handbook current

Show the current active handbook.

Usage:

onemcp handbook current

Output:

• Current handbook name
• Location path

Example:

onemcp handbook current
 
# Output:
# Current Handbook: acme-analytics
# Location: Built-in

handbook validate

Validate handbook structure.

Usage:

onemcp handbook validate [name]

Arguments:

• name (optional) - Handbook to validate. If omitted, validates current handbook.

Checks:

• Handbook directory exists
• openapi/ directory exists
• At least one .yaml file in openapi/
• Valid YAML syntax

Example:

onemcp handbook validate customer-api
 
# Output:
# ✓ Handbook structure valid
# ✓ OpenAPI directory found
# ✓ 2 OpenAPI specifications found
# ✓ No validation errors

Service Management

service auth

Configure authentication for external services.

Usage:

onemcp service auth

Interactive Prompts:

1. Service name
2. Authentication header (e.g., Authorization)
3. Token pattern (e.g., Bearer {token})
4. Token value
5. Expiration date

Creates: ~/onemcp-handbooks/{current-handbook}/service.yaml

Example:

onemcp service auth
 
# Interactive:
# ? Service name: my-api
# ? Header name: Authorization
# ? Token pattern: Bearer {token}
# ? Token value: **********************
# ? Expires at (YYYY-MM-DD): 2025-12-31
# ✓ Service authentication configured

Generated service.yaml:

service: my-api
header: Authorization
pattern: Bearer {token}
token: eyJhbGc...
expiresAt: 2025-12-31T23:59:59Z

service list

List all configured services.

Usage:

onemcp service list

Output:

• Service name
• Handbook
• Expiration date
• Status (valid/expired)

Example:

onemcp service list
 
# Output:
# Configured Services:
#   - customer-api (expires: 2025-12-31) [valid]
#   - payment-api (expires: 2025-06-30) [expired]

service renew

Renew service authentication token.

Usage:

onemcp service renew

Interactive Prompts:

1. Select service to renew
2. New token value
3. New expiration date

Updates:

• token field in service.yaml
• expiresAt field in service.yaml

Example:

onemcp service renew
 
# Interactive:
# ? Select service: customer-api
# ? New token value: **********************
# ? Expires at (YYYY-MM-DD): 2026-01-31
# ✓ Token renewed successfully

Shell Completion

completion

Generate autocompletion scripts for your shell.

Sub commands:

• bash - Bash completion
• zsh - Zsh completion
• fish - Fish completion
• powershell - PowerShell completion

Usage:

onemcp completion <shell>

Examples:

Bash:

# Generate completion script
onemcp completion bash > /etc/bash_completion.d/onemcp
 
# Or add to ~/.bashrc
source <(onemcp completion bash)

Zsh:

# Add to ~/.zshrc
source <(onemcp completion zsh)

Fish:

onemcp completion fish > ~/.config/fish/completions/onemcp.fish

PowerShell:

onemcp completion powershell | Out-String | Invoke-Expression

See Shell Completion Guide for detailed setup.

Configuration

Global Configuration File

Location: ~/.onemcp/config.yaml

Structure:

provider: gemini                  # Active AI provider
apikeys:
  gemini: YOUR_GEMINI_KEY
  openai: YOUR_OPENAI_KEY
  anthropic: YOUR_ANTHROPIC_KEY
currenthandbook: acme-analytics   # Active handbook
defaultport: 8080                 # Server port
handbookdir: /path/to/handbooks   # Handbooks directory
chattimeout: 240                  # Chat timeout (seconds)

Fields:

• provider (string) - Active AI provider (gemini, openai, anthropic)
• apikeys (object) - API keys for each provider
• currenthandbook (string) - Name of active handbook
• defaultport (integer) - Server port (default: 8080)
• handbookdir (string) - Path to handbooks directory
• chattimeout (integer) - Chat timeout in seconds (default: 240)

Manual Editing:

nano ~/.onemcp/config.yaml

Handbook Structure

Location: ~/onemcp-handbooks/{handbook-name}/

Structure:

handbook/
├── Agent.yaml              # AI instructions
├── README.md             # Handbook overview
├── getting-started.md    # Quick start guide
├── openapi/              # OpenAPI specs (REQUIRED)
│   └── api.yaml
├── docs/                 # Additional docs (optional)
└── data/                 # Data files (optional, not used by server)

Required:

• openapi/ directory with at least one .yaml file

Recommended:

• Agent.yaml - Instructions for the AI agent

Optional:

• README.md, getting-started.md - Documentation
• docs/ - Additional markdown files
• data/ - Data files (not processed by server)

Service Authentication File

Location: ~/onemcp-handbooks/{handbook-name}/service.yaml

Structure:

service: my-api                    # Service identifier
header: Authorization              # HTTP header name
pattern: Bearer {token}            # Token pattern
token: eyJhbGc...                  # Token value
expiresAt: 2025-12-31T23:59:59Z   # Expiration timestamp

Fields:

• service - Unique service identifier
• header - HTTP header for authentication
• pattern - Token pattern with {token} placeholder
• token - Actual token value
• expiresAt - ISO 8601 timestamp for expiration

Common Patterns:

# Bearer token
header: Authorization
pattern: Bearer {token}
 
# API key
header: X-API-Key
pattern: {token}
 
# Custom header
header: X-Custom-Auth
pattern: Token {token}

Environment Variables

Runtime Configuration

• ONEMCP_CONFIG - Override config file path
• ONEMCP_PORT - Override server port
• ONEMCP_HANDBOOK_DIR - Override handbooks directory

Examples:

# Use custom config
ONEMCP_CONFIG=/custom/config.yaml onemcp chat
 
# Use custom port
ONEMCP_PORT=9090 onemcp chat
 
# Use custom handbook directory
ONEMCP_HANDBOOK_DIR=/my/handbooks onemcp handbook list

Best Practices

Configuration Management

• Version control: Keep handbooks in Git, exclude service.yaml
• Secrets management: Never commit API keys or tokens to version control
• Environment separation: Use separate handbooks for dev/staging/prod

Handbook Organization

• One handbook per service: Keep each API separate
• Descriptive names: Use clear names like customer-api, not api1
• Documentation: Include comprehensive docs
• Validation: Run validate after changes

Service Authentication

• Token rotation: Regularly renew tokens using service renew
• Expiration dates: Set realistic expiration dates
• Least privilege: Use tokens with minimal permissions
• Secure storage: Protect configuration files

Troubleshooting

• Check logs first: onemcp logs to diagnose issues
• Verify health: onemcp status to check service health
• Run doctor: onemcp doctor to verify requirements
• Clean restart: onemcp stop then onemcp chat

See Also

• CLI Guide - Comprehensive usage guide
• CLI Installation - Installation methods
• Shell Completion - Tab completion setup
• Development CLI - Local development tools