CLI Guide

Complete guide to using the OneMCP CLI - your command center for connecting APIs to AI models.

Installation

See CLI Installation for detailed instructions.

Quick install:


# macOS/Linux
brew tap gentoro-onemcp/onemcp
brew install onemcp
 
# Windows
scoop bucket add gentoro-onemcp https://github.com/Gentoro-OneMCP/onemcp-scoop
scoop install onemcp

First Steps

Start a Chat Session


onemcp chat

On first run, the setup wizard will:

Ask for your AI provider (OpenAI, Gemini, Anthropic)
Request your API key
Set up initial configuration
Start the OneMCP server (Docker)

Example Session


╔══════════════════════════════════════╗
║    Gentoro OneMCP - Chat Mode        ║
╚══════════════════════════════════════╝

Handbook: acme-analytics
Provider: gemini

You: Show total sales for 2024
Agent: {
  "message": "Total revenue for 2024 computed successfully.",
  "total_revenue": 5640255.26
}

In-Chat Commands:

help - Show available commands
clear - Clear chat history
switch - Switch to different handbook
exit or quit - Exit chat

Core Commands

Chat

Start interactive chat session.


onemcp chat

Starts Docker container and connects to MCP server.

Features:

ACME Analytics example prompts (when using built-in handbook)
Persistent chat history within session
Automatic server startup

Status

Show server and configuration status.


onemcp status

Displays:

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

Stop

Stop the OneMCP server.


onemcp stop

Gracefully stops Docker container and cleans up resources.

Logs

View server logs.


onemcp logs              # Show recent logs (last 50 lines)
onemcp logs -n 100       # Show last 100 lines
onemcp logs -f           # Follow logs in real-time

Use cases:

Debugging connection issues
Monitoring server performance
Viewing API call traces

Doctor

Check system requirements and configuration.


onemcp doctor

Verifies:

Docker installation
Docker daemon running
Network connectivity
Configuration file validity
Required permissions

Troubleshooting: Run this first if experiencing issues.

Update

Update OneMCP Docker image and get CLI update instructions.


onemcp update

What it does:

Detects how the CLI was installed (Homebrew/Scoop/Manual)
Shows appropriate update instructions for the CLI binary
Pulls the latest OneMCP Docker image

Example output:


📌 To update the OneMCP CLI:

  Homebrew:
    brew upgrade onemcp

📦 Updating OneMCP Docker image...
latest: Pulling from admingentoro/gentoro
✅ Docker image updated successfully!

To update the CLI itself:

Homebrew: brew upgrade onemcp
Scoop: scoop update onemcp
Manual: Download from GitHub Releases

Note: The update command updates the Docker image. To update the CLI binary, follow the instructions shown.

Version

Show CLI version.


onemcp version
# or
onemcp --version

Displays the installed CLI version.

Reset

Reset all configuration.


onemcp reset

Warning: Deletes all configuration files. Handbooks are preserved.

When to use:

Starting fresh with new configuration
Resolving configuration corruption
Switching to completely different setup

Provider Management

Manage AI model providers (OpenAI, Google Gemini, Anthropic Claude).

Set Provider

Configure an AI provider.


onemcp provider set

Interactive prompts:

Choose provider (OpenAI, Gemini, Anthropic)
Enter API key
Configuration saved to ~/.onemcp/config.yaml

Example:


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

List Providers

Show all configured providers.


onemcp provider list

Output:


Configured Providers:
  ✓ gemini: AIza************************ (active)
  ✓ openai: sk-proj-********************
  - anthropic: (not configured)

Shows masked API keys for security.

Switch Provider

Switch between configured providers.


onemcp provider switch

Interactive selection from configured providers. No need to re-enter API keys.

Handbook Management

Manage API handbook directories.

List Handbooks

Show all available handbooks.


onemcp handbook list

Output:


Available Handbooks:
  - acme-analytics (built-in)
  - customer-api
  - analytics-service

Use Handbook

Set active handbook.


onemcp handbook use customer-api    # Specific handbook
onemcp handbook use                 # Interactive selection

Sets which handbook the onemcp chat command will use.

Current Handbook

Show current active handbook.


onemcp handbook current

Output:


Current Handbook: acme-analytics
Location: Built-in

Initialize Handbook

Create a new handbook.


onemcp handbook init my-api

Creates directory structure:


~/onemcp-handbooks/my-api/
├── Agent.yaml              # Created with template
├── README.md             # Created with template
├── getting-started.md    # Created with template
└── openapi/              # Created (empty)
    └── README.md         # Created with instructions

Next steps after init:

Add OpenAPI spec to openapi/ directory
Customize Agent.yaml with instructions
Run onemcp handbook validate my-api
Use with onemcp handbook use my-api

Validate Handbook

Check handbook structure.


onemcp handbook validate           # Validate current
onemcp handbook validate my-api    # Validate specific

Checks:

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

Example output:


✓ Handbook structure valid
✓ OpenAPI directory found
✓ 2 OpenAPI specifications found

Service Management

Manage authentication for external services that your APIs interact with.

Configure Authentication

Set up service authentication.


onemcp service auth

Interactive prompts:

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

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


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

List Services

Show configured services.


onemcp service list

Output:


Configured Services:
  - customer-api (expires: 2025-12-31)
  - analytics-api (expires: 2025-06-30)

Renew Token

Update existing service token.


onemcp service renew

Prompts for new token and expiration date.

Shell Completion

Enable tab completion for faster CLI usage.

Setup

Bash:


# 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

Usage

After setup:


onemcp ha<TAB>          → handbook
onemcp handbook <TAB>   → shows: init, list, use, current, validate

See Shell Completion Guide for detailed setup.

Configuration

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)

Manual Editing

Edit with any text editor:


nano ~/.onemcp/config.yaml

Common edits:

Change default port
Update handbook directory location
Adjust chat timeout

Troubleshooting

Docker Not Running


# Check Docker
docker ps
 
# macOS/Windows: Start Docker Desktop
# Linux: Start Docker daemon
sudo systemctl start docker

Symptoms:

onemcp chat fails immediately
onemcp doctor reports Docker issues

Port Already in Use

Port 8080 is occupied by another service.

Diagnosis:


# macOS/Linux
lsof -i :8080
 
# Windows
netstat -ano | findstr :8080

Solutions:

Stop conflicting service
Change port in ~/.onemcp/config.yaml

Connection Issues


# Check status
onemcp status
 
# View error logs
onemcp logs
 
# Restart everything
onemcp stop
onemcp chat

Common causes:

Docker not running
Network connectivity issues
Incorrect API key
Expired service token

Invalid Handbook


onemcp handbook validate

Common issues:

Missing openapi/ directory
No .yaml files in openapi/
Invalid YAML syntax

Fix:


# Ensure openapi directory exists
mkdir -p ~/onemcp-handbooks/my-handbook/openapi
 
# Add OpenAPI spec
cp api.yaml ~/onemcp-handbooks/my-handbook/openapi/
 
# Validate
onemcp handbook validate my-handbook

API Key Issues


# List configured providers
onemcp provider list
 
# Reconfigure provider
onemcp provider set
 
# Switch providers
onemcp provider switch

Complete Reset

If nothing else works:


onemcp reset

Deletes all configuration and reruns setup wizard.

Note: Handbooks are preserved.

Best Practices

API Keys

Never commit API keys to version control
Use environment variables in CI/CD
Rotate keys regularly for security
Store keys using secure vaults in production

Chat Sessions

Use clear to reset context for new topics
Use switch to change handbooks mid-session
Use help to discover available commands
Review chat history for debugging

Logging

Use logs -f to debug issues in real-time
Logs persist even after restart
Location: Docker container logs (accessible via onemcp logs)

Handbooks

One handbook per service - Keep each API separate
Descriptive names - Use clear names like customer-api
Version control - Consider versioning handbooks with Git
Validate regularly - Run validate after changes

Next Steps

Installation: See CLI Installation for all methods
Reference: Check CLI Reference for complete command documentation
Shell Completion: Set up Shell Completion for efficiency
Docker Deploy: Learn about Running with Docker
Development: Explore Dev CLI for local development