OneXEOS Platform CLI (onex)

Official CLI for deploying and managing services on the OneXEOS Platform

📋 Table of Contents

• Overview
• Installation
• Quick Start
  • Platform-Specific Setup Guides
• Commands
• SEO & AI-Search Audit
• VPN Setup
• Environment Management
• Configuration
• Development
• For Platform Developers
• Windows Support
• Troubleshooting

📖 Detailed Guides:

• Complete Setup Guide - Step-by-step for macOS/Linux/Windows
• Windows Compatibility Guide - Windows-specific details
• MCP Service Developer Guide - AI debugging with Claude Code

Overview

The onex CLI provides a unified interface for:

• 🚀 One-command setup: VPN + login + .env generation (onex init)
• 🔐 VPN management: Cross-platform WireGuard VPN setup (Mac, Linux, Windows)
• 📦 Service deployment: Deploy to local/dev/staging/prod environments
• 🐛 Visual debugging: VS Code debugging with breakpoints (onex debug)
• 🔍 Request tracing: End-to-end request debugging with trace_id
• 📊 Monitoring: View logs, status, and health checks
• ⚡ Hot reload: Auto-reload on code changes during development
• 🔧 Resource management: Provision MongoDB, Redis, Elasticsearch resources

Installation

For Service Developers (PyPI)

# Install from PyPI (recommended)
pip install onex-cli

# Or add to requirements.txt
onex-cli>=1.0.0

# Verify installation
onex --version

That's it! No platform repository access needed.

For Platform Developers

# Install from source (development)
cd onexeos-platform-NEW/onex-cli
pip install -e .

Quick Start

First-Time Setup (3 Steps)

# Step 1: Install CLI
pip install onex-cli

# Step 2: Initialize environment (VPN + login + .env)
onex init

# Step 3: Create your first service (NEW in v1.4.0!)
onex create

What onex init does:

1. ✅ Sets up VPN from config file (if you have one)
2. ✅ Auto-extracts credentials from VPN config (NEW in v1.1.0!)
3. ✅ Logs into platform (no manual password entry!)
4. ✅ Downloads credentials (MongoDB, Redis, JWT secrets)
5. ✅ Auto-generates .env file
6. ✅ Verifies connectivity
7. ✅ Configures MCP for Claude Code (optional - NEW in v1.3.3!)

What onex create does (NEW in v1.4.0!):

1. ✅ Interactive wizard to select template (REST API, Event-Driven, CRUD, Minimal)
2. ✅ Generates complete service structure from template
3. ✅ Validates service.yml automatically
4. ✅ Shows next steps to deploy

You're ready to develop! 🎉

NEW in v1.1.0: No more manual password entry! If your VPN config contains embedded credentials, onex init will automatically extract and use them for login.

NEW in v1.3.3: MCP (Model Context Protocol) integration allows Claude Code to debug your platform with natural language: "Is my platform healthy?", "Debug trace_id: abc123", "Show email-service logs"

Platform-Specific Setup Guides

Choose your operating system for detailed step-by-step instructions:

📖 Complete Setup Guide ← Comprehensive guide for all platforms

Quick links by platform:

• 🍎 macOS Setup - Homebrew + wg-quick
• 🐧 Linux Setup - systemd + auto-install
• 🪟 Windows Setup - WireGuard GUI

Key differences:

• macOS/Linux: VPN managed via command-line (wg-quick, systemctl)
• Windows: VPN managed via WireGuard GUI application

All other commands are identical across platforms.

Deploy Your First Service

cd services/demo
onex deploy

Debug Locally with VS Code

# Start service with debugger
onex debug --service demo

# Output:
# 🐛 VS Code debugging enabled on port 5678
#    Press F5 in VS Code to attach debugger
#
# 📦 Loading service: demo
# ✅ Loaded demo: 7 routes
# 📡 Access at: http://localhost:8001/docs

# Press F5 in VS Code → Set breakpoints → Make request

Commands

Core Commands

onex init                          # Setup VPN + login + .env (one command!)
onex create                        # Create new service from template (NEW v1.4.0!)
onex deploy                        # Deploy service to platform
onex debug --service <name>        # Debug service locally (VS Code ready)
onex trace <trace_id>              # Trace request through platform
onex logs <service> --follow       # Stream service logs
onex status <service>              # Check service health

All Commands

SEO & AI-Search Audit (onex seo)

Audits a website across three axes and emits a prioritized checklist of fixes — not just a score. You supply the target keywords; it scores how well each page serves them.

Setup (one time)

onex seo setup          # installs deps + Chromium, then verifies everything

That's it — setup installs what's missing, checks what's there, and tells you what to run next. It's safe to re-run, and onex seo setup --check reports status without installing anything.

pip install 'onex-cli[seo]'
playwright install chromium

Use it

onex seo init-keywords                      # 1. write a starter keywords.yaml
$EDITOR keywords.yaml                       # 2. the keywords YOU want to rank for
onex seo audit https://yoursite.com \
    -k keywords.yaml --html report.html     # 3. crawl, score, get the checklist

Why an optional extra? AI crawlers do not execute JavaScript, so a client-rendered SPA serves them an empty page. The only honest way to detect that is to render every page in a real browser — which means Chromium (~400MB). It stays opt-in so pip install onex-cli remains as light as it is today, and running onex seo without it prints onex seo setup rather than a traceback.

What it checks

Plus a Keyword Coverage score on its own axis: per-keyword placement, subtopic coverage, intent match, and whether the page carries a citable answer block.

The findings most tools miss

• Blocking GPTBot is fine. Training bots (GPTBot, ClaudeBot, CCBot) cost you zero citations. Retrieval bots (OAI-SearchBot, PerplexityBot) remove you from live AI answers within hours. The auditor classifies by purpose, not allow/deny.
• Orphan keywords — no page targets a keyword you care about. That's a content gap, so you get "create this page, here's the title, here's what it must cover."
• Cannibalization — several pages compete for one keyword and split their authority. You get a named winner and a 301 plan.

--probe: measure real AI citations

Every other AI-search check is a proxy for "will an LLM cite this page." --probe measures the outcome directly: it turns each keyword into the questions a human would actually ask an assistant, runs them with web search, and counts how often your domain comes back as a cited source.

No API key needed if you have Claude Code installed — it reuses your existing login. With ANTHROPIC_API_KEY set it uses the SDK instead (stronger evidence: citations come from structured search-result blocks rather than the model reporting its own sources).

What it deliberately does not measure

Search volume, keyword difficulty, and rankings. All three require scraping Google or a paid data vendor, and a fabricated number sitting next to real ones poisons trust in all of them.

VPN Setup

NEW in v1.0.0: Built-in VPN management for dev/staging/prod access.

Automatic Setup (Recommended)

# One command does everything
onex init

# Prompts:
# - Do you have a VPN config file? [Y/n]: y
# - VPN config file path: ~/Downloads/alice-dev.conf
#
# Then automatically:
# ✅ Installs WireGuard (if needed)
# ✅ Imports config
# ✅ Connects to VPN
# ✅ Verifies connectivity
# ✅ Logs into platform
# ✅ Generates .env file

Manual VPN Management

# Setup VPN from config file
onex vpn setup ~/Downloads/alice-dev.conf

# Switch to dev environment (connects VPN + sets active)
onex switch dev

# Check VPN status
onex vpn status

# Switch to local (disconnects VPN)
onex switch local

Platform-Specific Instructions

macOS:

• Uses Homebrew + wg-quick
• Requires sudo for VPN operations

Linux:

• Auto-installs WireGuard (Ubuntu/Debian/CentOS/RHEL)
• Uses systemd for VPN management

Windows:

• GUI app recommended: https://www.wireguard.com/install/
• Or use manual import in WireGuard app

See service repository's docs/platform/VPN_SETUP_DEVELOPER.md for detailed guide.

Environment Management

Active Environment Concept

The active environment determines where commands deploy to:

# Show active environment
onex env
# ✅ Active environment: local

# Switch to dev (connects VPN + sets active)
onex switch dev
# ✅ Switched to: dev

# Now all commands use dev
onex deploy  # Deploys to dev
onex logs    # Shows dev logs

Available Environments

Note: IP addresses are examples and can be customized for your deployment.

Login to Environment

# Login to local (no VPN needed)
onex login --env local

# Switch to dev (connects VPN + logs in if credentials embedded)
onex switch dev
# ✅ Connects to VPN
# ✅ Sets dev as active environment

# Or use onex init for complete setup
onex init --config-file ~/Downloads/alice-dev.conf

Platform Architecture

Access Methods

The OneXEOS platform provides three access methods:

1. Public Access (via Domain + SSL)

• Dev: https://dev.onexeos.com → Traefik → Gateway → Services
• Staging: https://staging.onexeos.com → Traefik → Gateway → Services
• Production: https://onexeos.com → Traefik → Multi-Replica Gateway → Services

2. VPN Access (Direct to Gateway)

• Dev: http://10.0.0.1:8000 (via VPN)
• Staging: http://10.0.1.1:8000 (via VPN)
• Production: http://10.0.2.1:8000 (via VPN)

3. Initial Login (Public Auth Service)

• All Environments: http://103.17.141.76:8100 (no VPN required)
• Used during onex init for first-time authentication

Developer Workflow

# Step 1: Receive VPN config from DevOps
# Contains: Embedded credentials + Public auth URL + VPN config

# Step 2: Initialize environment
onex init --config-file alice-dev.conf
# ✅ Parses VPN config
# ✅ Authenticates via public auth (103.17.141.76:8100) - no VPN needed!
# ✅ Prompts to connect VPN
# ✅ Downloads credentials from gateway (10.0.0.1:8000) - requires VPN
# ✅ Saves environment config

# Step 3: Deploy your service
onex deploy
# Uses VPN gateway (10.0.0.1:8000) for deployment

# Step 4: Access via domain (public) OR VPN (direct)
# Public:  https://dev.onexeos.com/api/your-service/...
# Direct:  http://10.0.0.1:8000/api/your-service/...

URL Reference

Configuration

Credential Storage

Credentials stored securely in ~/.onex/:

~/.onex/
├── environments.json    # Environment credentials (MongoDB, Redis, JWT, etc.)
└── active-env          # Currently active environment

Security:

• Never commit .env files
• Never share ~/.onex/ directory
• Files automatically created with restrictive permissions (600)

Auto-Generated .env File

When you run onex login or onex init, a .env file is automatically created in your service repository:

# MongoDB
MONGODB_URI=mongodb://user:pass@host:27017/db?authSource=admin
MONGODB_DATABASE=onexeos

# Redis
REDIS_URI=redis://:password@host:6379/0

# JWT
JWT_SECRET=<auto-downloaded-secret>
JWT_ALGORITHM=HS256

# Platform
PLATFORM_URL=http://10.0.0.1:8000

# Development
DEBUG=true
ENV=dev

Development

Debug Workflow

# Navigate to service directory
cd services/product

# Start debugging (VS Code ready!)
onex debug --service product

# Output:
# 🐛 VS Code debugging enabled on port 5678
#    Press F5 in VS Code to attach debugger
#
# 📦 Loading service: product
#    ✅ POST   /products                → src.handlers.create_product
#    ✅ GET    /products/{id}           → src.handlers.get_product
#
# ✅ Loaded product: 5 routes
# 📡 Access at: http://localhost:8001/docs

# In VS Code:
# 1. Set breakpoints (click left margin)
# 2. Press F5 → Select "Attach to Runtime"
# 3. Make request: curl http://localhost:8001/products/123
# 4. VS Code pauses at your breakpoints!

Features:

• ✅ Hot reload on code changes
• ✅ VS Code breakpoint debugging
• ✅ Interactive API docs at /docs
• ✅ Auto-registers routes with platform gateway

Request Tracing

Every request gets a unique trace_id:

# 1. Make request
curl -D /tmp/headers.txt http://localhost:8001/products/123

# 2. Extract trace_id from response header
grep x-trace-id /tmp/headers.txt
# x-trace-id: 550e8400-e29b-41d4-a716-446655440000

# 3. View complete request timeline
onex trace 550e8400-e29b-41d4-a716-446655440000

# Output shows Gateway → Runtime → Service flow:
# 🔍 Querying trace: 550e8400-e29b-41d4-a716-446655440000
#
# ✅ Found 12 log entries
# ⏱️  Total Duration: 456ms
#
# 📦 GATEWAY
#   14:23:45.123 INFO    POST /products/123
#   14:23:45.145 INFO    Forwarding to product service
#
# 📦 RUNTIME
#   14:23:45.156 INFO    Executing product:get_product
#
# 📦 SERVICE
#   14:23:45.267 INFO    Product found: 123
#   14:23:45.456 INFO    POST /products/123 200 456ms

For Platform Developers

This CLI is maintained by the platform team.

Development Setup

cd onexeos-platform-NEW/onex-cli
pip install -e .

# Make changes to CLI
vim onex/commands/mycommand.py

# Test immediately (editable mode)
onex mycommand

Publishing to PyPI

See PUBLISHING.md for complete guide.

Quick reference:

# 1. Update version and changelog
vim setup.py CHANGELOG.md

# 2. Run verification script
./verify-package.sh

# 3. Build and test on TestPyPI
rm -rf dist/
python -m build
twine upload --repository testpypi dist/*

# 4. Test installation
pip install --index-url https://test.pypi.org/simple/ onex-cli

# 5. Publish to production PyPI
twine upload dist/*

# 6. Tag release
git tag -a v1.0.1 -m "Release 1.0.1"
git push origin v1.0.1

Adding New Commands

1. Create command file in onex/commands/:

# onex/commands/mycommand.py
import click
from onex.utils import print_success, print_error

@click.command()
@click.option('--env', default='local', help='Environment')
def mycommand(env):
    """Description of new command"""
    print_success("Command completed!")

2. Register in onex/__main__.py:

from onex.commands import mycommand
cli.add_command(mycommand.mycommand)

3. Test:

onex mycommand --help

Directory Structure

onex-cli/
├── setup.py                 # PyPI package configuration
├── MANIFEST.in             # Package files to include
├── LICENSE                 # MIT License
├── CHANGELOG.md            # Version history
├── PUBLISHING.md           # Publishing guide
├── README.md               # This file
└── onex/
    ├── __init__.py
    ├── __main__.py         # CLI entry point
    ├── config.py           # Configuration management
    ├── utils.py            # Shared utilities
    ├── commands/           # Command implementations
    │   ├── debug.py       # Debug service locally
    │   ├── deploy.py      # Deploy to platform
    │   ├── dev.py         # Development mode (deprecated)
    │   ├── env.py         # Environment management
    │   ├── init.py        # VPN + login + .env setup
    │   ├── invoke.py      # Function invocation
    │   ├── login.py       # Platform authentication
    │   ├── logout.py      # Logout
    │   ├── logs.py        # View service logs
    │   ├── platform.py    # Platform management
    │   ├── provision.py   # Resource provisioning
    │   ├── status.py      # Service health
    │   ├── trace.py       # Request tracing
    │   ├── validate.py    # Schema validation
    │   └── vpn.py         # VPN management (NEW)
    ├── runtime/
    │   └── local_runtime.py  # Local service runtime
    ├── schema/
    │   └── service_descriptor.py  # Service schema
    └── vpn/               # VPN module (NEW)
        ├── __init__.py
        ├── platform_detector.py    # OS/environment detection
        ├── setup_vpn.py           # VPN orchestration
        └── wireguard_manager.py   # WireGuard operations

Windows Support

Full Windows compatibility! The OneX CLI works perfectly on Windows 10/11 with PowerShell and Command Prompt.

Quick Start on Windows

# Install CLI
pip install onex-cli

# Verify installation
onex --version

# Setup MCP for Claude Code (optional)
onex mcp setup

Key Differences on Windows

VPN on Windows: Use the WireGuard GUI application instead of command-line tools. Import your .conf file and activate the tunnel manually.

For complete Windows guide: See WINDOWS_COMPATIBILITY.md

Troubleshooting

Command not found: onex

# Reinstall from PyPI
pip install --upgrade onex-cli

# Verify installation
which onex
onex --version

Platform connection failed

# Check VPN connection
onex vpn status

# Reconnect if needed
onex switch dev

# Verify platform health
onex platform check

VPN setup failed

macOS:

# Install WireGuard via Homebrew
brew install wireguard-tools

# Try setup again
onex vpn setup ~/Downloads/alice-dev.conf

Linux:

# Ubuntu/Debian
sudo apt update
sudo apt install wireguard wireguard-tools

# CentOS/RHEL
sudo yum install epel-release
sudo yum install wireguard-tools

# Try setup again
onex vpn setup ~/Downloads/alice-dev.conf

Windows: Download WireGuard GUI: https://www.wireguard.com/install/

"Module not found" errors

# Reinstall dependencies
pip install --upgrade onex-cli

# Or reinstall everything
pip install -r requirements.txt --upgrade

Deployment failed

# Validate service.yml first
onex validate

# Check platform health
onex platform check

# View detailed logs
onex logs deployment-controller --follow

Version History

See CHANGELOG.md for detailed version history.

Current Version: 1.0.1

• ✅ VPN module (cross-platform support)
• ✅ One-command setup (onex init)
• ✅ VS Code debugging with debugpy
• ✅ Auto-generated .env files
• ✅ Published to PyPI
• ✅ Comprehensive documentation

Support

For Service Developers

• Installation: pip install onex-cli
• Documentation: This README + service repo docs
• Issues: Contact platform team

For Platform Developers

• Development: Install from source (pip install -e .)
• Publishing: See PUBLISHING.md
• Issues: GitHub issues in platform repository

Related Documentation

Service Developers:

• Developer Guide
• VPN Setup Guide
• Quick Start

Platform Developers:

• Publishing Guide
• Changelog
• Platform Architecture

License

MIT License - See LICENSE file.

Links

• PyPI: https://pypi.org/project/onex-cli/
• GitHub: https://github.com/onexeos/onex-cli
• Issues: https://github.com/onexeos/onex-cli/issues

Maintained by: OneXEOS Platform Team Used by: Service Developers (no platform repo access needed!) Version: 1.0.1