Metadata-Version: 2.4
Name: onex-cli
Version: 1.9.5
Summary: Official CLI for deploying and managing services on OneXEOS Platform (Windows, macOS, Linux)
Home-page: https://github.com/onexeos/onex-cli
Author: OneXEOS Platform Team
Author-email: platform@onexeos.com
Project-URL: Documentation, https://github.com/onexeos/onex-cli#readme
Project-URL: Bug Reports, https://github.com/onexeos/onex-cli/issues
Project-URL: Source, https://github.com/onexeos/onex-cli
Project-URL: Changelog, https://github.com/onexeos/onex-cli/blob/main/CHANGELOG.md
Keywords: onexeos platform cli deployment serverless microservices vpn wireguard windows macos linux cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: paramiko>=3.4.0
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pymongo>=4.6.0
Requires-Dist: redis>=5.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: pywin32>=306; platform_system == "Windows"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# OneXEOS Platform CLI (`onex`)

**Official CLI for deploying and managing services on the OneXEOS Platform**

[![PyPI version](https://badge.fury.io/py/onex-cli.svg)](https://pypi.org/project/onex-cli/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
  - [Platform-Specific Setup Guides](#platform-specific-setup-guides)
- [Commands](#commands)
- [VPN Setup](#vpn-setup)
- [Environment Management](#environment-management)
- [Configuration](#configuration)
- [Development](#development)
- [For Platform Developers](#for-platform-developers)
- [Windows Support](#windows-support)
- [Troubleshooting](#troubleshooting)

**📖 Detailed Guides:**
- [Complete Setup Guide](SETUP_GUIDE.md) - Step-by-step for macOS/Linux/Windows
- [Windows Compatibility Guide](WINDOWS_COMPATIBILITY.md) - Windows-specific details
- [MCP Service Developer Guide](onex/mcp/SERVICE_DEVELOPER_GUIDE.md) - 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)

```bash
# 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

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

---

## Quick Start

### First-Time Setup (3 Steps)

```bash
# 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](SETUP_GUIDE.md)** ← Comprehensive guide for all platforms

**Quick links by platform:**
- 🍎 [macOS Setup](SETUP_GUIDE.md#macos-setup) - Homebrew + wg-quick
- 🐧 [Linux Setup](SETUP_GUIDE.md#linux-setup) - systemd + auto-install
- 🪟 [Windows Setup](SETUP_GUIDE.md#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

```bash
cd services/demo
onex deploy
```

### Debug Locally with VS Code

```bash
# 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

```bash
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 |
| **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)

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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`:

```bash
# 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

```bash
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](PUBLISHING.md) for complete guide.

**Quick reference:**

```bash
# 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/`:

```python
# 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`**:

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

3. **Test**:

```bash
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

```powershell
# 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](https://www.wireguard.com/install/) instead of command-line tools. Import your `.conf` file and activate the tunnel manually.

**For complete Windows guide:** See [WINDOWS_COMPATIBILITY.md](WINDOWS_COMPATIBILITY.md)

---

## Troubleshooting

### Command not found: onex

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

# Verify installation
which onex
onex --version
```

### Platform connection failed

```bash
# Check VPN connection
onex vpn status

# Reconnect if needed
onex switch dev

# Verify platform health
onex platform check
```

### VPN setup failed

**macOS:**
```bash
# Install WireGuard via Homebrew
brew install wireguard-tools

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

**Linux:**
```bash
# 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

```bash
# Reinstall dependencies
pip install --upgrade onex-cli

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

### Deployment failed

```bash
# 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](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](PUBLISHING.md)
- **Issues**: GitHub issues in platform repository

---

## Related Documentation

**Service Developers:**
- [Developer Guide](https://github.com/onexeos/onexeos-services/blob/main/DEVELOPER_GUIDE.md)
- [VPN Setup Guide](https://github.com/onexeos/onexeos-services/blob/main/docs/platform/VPN_SETUP_DEVELOPER.md)
- [Quick Start](https://github.com/onexeos/onexeos-services/blob/main/README.md#quick-start)

**Platform Developers:**
- [Publishing Guide](PUBLISHING.md)
- [Changelog](CHANGELOG.md)
- [Platform Architecture](../docs/ARCHITECTURE.md)

---

## License

MIT License - See [LICENSE](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
