onex-cli 1.18.0

Official CLI for deploying and managing services on OneXEOS Platform (Windows, macOS, Linux)

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
• 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

Command	Description
Setup & Auth
onex init	Initialize environment (VPN + login + .env)
onex login	Login to platform and download credentials
onex logout	Logout and remove stored credentials
Environment Switching (NEW v1.2.0)
onex switch <env>	Switch environment (handles VPN + config)
VPN Management
onex vpn setup <file>	Setup VPN from WireGuard config file
onex vpn status	Show VPN connection status
onex vpn list	List all configured VPNs
Environment Info
onex env	Show active environment
onex env list	List all configured environments
onex env show <env>	Show environment details
onex env sync	Regenerate .env file
Service Scaffolding (NEW v1.4.0)
onex create	Create new service from template (interactive)
onex create -n <name> -t <template>	Create service with specific template
Development
onex debug --service <name>	Debug service locally (VS Code + hot reload)
onex dev	Run service locally with hot-reload (deprecated, use debug)
Deployment
onex deploy	Deploy service to active environment
onex validate	Validate service.yml schema
onex provision	Manually provision MongoDB resources
Monitoring
onex logs <service>	View service logs
onex status <service>	Check service status
onex trace <trace_id>	Debug request flow end-to-end
Invocation
onex invoke <service>:<fn>	Invoke function directly
Elasticsearch
onex es status [service]	View es_sync trigger status and health
onex es mapping [service]	Check ES mappings vs model definitions
onex es reindex <service>	Reindex ES from MongoDB
onex es reindex <service> --recreate	Recreate index with correct mappings + reindex
onex es test <service>	Test es_sync end-to-end
Platform
onex platform check	Check platform health

---

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

Environment	Platform URL	VPN Required	Access
local	http://localhost:8000	No	Full (contact platform team for setup)
dev	http://10.0.0.1:8000	Yes	Deploy + Read
staging	http://10.0.1.1:8000	Yes	Read only
prod	http://10.0.2.1:8000	Yes	Read only

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

Environment	Public (SSL)	VPN Gateway	Auth (Public)
Dev	https://dev.onexeos.com	http://10.0.0.1:8000	http://103.17.141.76:8100
Staging	https://staging.onexeos.com	http://10.0.1.1:8000	http://103.17.141.76:8100
Production	https://onexeos.com	http://10.0.2.1:8000	http://103.17.141.76:8100

---

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

Feature	Windows	macOS/Linux
CLI Commands	✅ Identical	✅ Identical
MCP Setup	✅ onex mcp setup	✅ onex mcp setup
VPN Setup	⚠️ WireGuard GUI	✅ wg-quick CLI
Path Handling	✅ Automatic	✅ Automatic

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