onex-cli 1.0.0

Official CLI for deploying and managing services on OneXERP Platform

OneXERP Platform CLI (onex)

Official CLI tool for deploying and managing services on the OneXERP Platform.

Overview

The onex CLI provides a unified interface for:

• Deploying services to different environments (local/dev/staging/prod)
• Validating service configurations (service.yml)
• Invoking service functions directly
• Tracing requests through the platform
• Viewing service logs and status
• Managing service resources

Installation

For Service Developers

# From onexerp-services repository root:
pip install -e ../onexerp-platform-NEW/onex-cli

# Or add to requirements.txt:
onex-cli @ file:../onexerp-platform-NEW/onex-cli

For Platform Developers

The CLI is automatically available when working in the platform repository:

# From onexerp-platform-NEW:
cd onex-cli
pip install -e .

Usage

Deploy a Service

# Deploy to local environment
onex deploy

# Deploy to specific environment
onex deploy --env dev
onex deploy --env staging
onex deploy --env prod

# Deploy from specific directory
onex deploy --service-dir ./services/product

Validate Service Configuration

# Validate service.yml without deploying
onex validate

# Validate specific service
onex validate --service-dir ./services/product

Invoke Functions

# Sync invoke (returns result immediately)
onex invoke product:calculateTotal '{"items": [...]}'

# Async invoke (fire and forget)
onex invoke --async product:processLargeFile '{"file_id": "123"}'

# Specify environment
onex invoke --env dev product:calculateTotal '{"items": [...]}'

Trace Requests

# Trace a request by trace_id
onex trace 550e8400-e29b-41d4-a716-446655440000

# Trace with environment
onex trace 550e8400-e29b-41d4-a716-446655440000 --env local

# Follow trace in real-time
onex trace 550e8400-e29b-41d4-a716-446655440000 --follow

# JSON output
onex trace 550e8400-e29b-41d4-a716-446655440000 --json

View Service Status

# Check service health and deployment status
onex status product

# Check all services
onex status

# Specify environment
onex status product --env dev

View Logs

# View service logs
onex logs product

# Follow logs in real-time
onex logs product --follow

# Last N lines
onex logs product --lines 100

Development Mode

# Run service locally with hot-reload
onex dev

# Specify service directory
onex dev --service-dir ./services/product

# Specify port
onex dev --port 8001

Initialize Configuration

# Interactive configuration setup
onex init

# Creates ~/.onex/config.yml with platform URLs and API keys

Provision Resources

# Manually provision MongoDB collections, indexes, etc.
onex provision

# Specify environment
onex provision --env dev

Configuration

The CLI uses ~/.onex/config.yml for environment-specific settings:

environments:
  local:
    platform_url: http://localhost:8000
    deployment_url: http://localhost:8002
  dev:
    platform_url: https://dev-platform.onexerp.com
    deployment_url: https://dev-platform.onexerp.com:8002
    api_key: ${ONEX_DEV_API_KEY}
  staging:
    platform_url: https://staging-platform.onexerp.com
    deployment_url: https://staging-platform.onexerp.com:8002
    api_key: ${ONEX_STAGING_API_KEY}
  prod:
    platform_url: https://platform.onexerp.com
    deployment_url: https://platform.onexerp.com:8002
    api_key: ${ONEX_PROD_API_KEY}

Service Configuration

Services must include a service.yml file:

name: product
version: 1.0.0
description: Product management service

deployment:
  mode: shared-runtime

functions:
  - name: getProduct
    handler: src.handlers.get_product
    triggers:
      - type: http
        path: /products/{id}
        method: GET

  - name: calculateTotal
    handler: src.handlers.calculate_total
    triggers: []  # Invoke-only function

  - name: processFile
    handler: src.handlers.process_file
    triggers:
      - type: s3
        bucket: product-uploads
        events: ["s3:ObjectCreated:*"]
        prefix: images/

Commands Reference

Command	Description
onex init	Initialize CLI configuration (interactive)
onex validate	Validate service.yml schema without deploying
onex deploy	Deploy service to platform
onex dev	Run service locally with hot-reload
onex invoke	Invoke service functions directly
onex trace	Track requests through platform with trace_id
onex logs	View service logs
onex status	Check service status and health
onex provision	Manually provision MongoDB resources

Development

Architecture

onex-cli/
├── setup.py                 # Package configuration
├── README.md               # This file
└── onex/
    ├── __init__.py
    ├── __main__.py         # CLI entry point
    ├── config.py           # Configuration management
    ├── utils.py            # Shared utilities
    ├── commands/           # Command implementations
    │   ├── deploy.py
    │   ├── trace.py
    │   ├── invoke.py
    │   ├── validate.py
    │   ├── logs.py
    │   ├── status.py
    │   ├── dev.py
    │   ├── init.py
    │   └── provision.py
    └── schema/
        ├── service_descriptor.py → ../../platform-services/shared/schema/service_descriptor.py
        └── validator.py

Adding New Commands

1. Create command file in onex/commands/
2. Implement using Click decorators
3. Register in onex/__main__.py

Example:

# onex/commands/newcommand.py
import click
from onex.config import get_config
from onex.utils import print_success, print_error

@click.command()
@click.option('--env', default='local', help='Environment')
def newcommand(env):
    """Description of new command"""
    config = get_config(env)
    # Implementation here
    print_success("Command completed!")

# Register in onex/__main__.py
from onex.commands import newcommand
cli.add_command(newcommand.newcommand)

Platform Integration

The CLI integrates with these platform services:

• Deployment Controller (8002) - Service deployment and versioning
• Gateway (8000) - HTTP routing and function invocation
• Loki (3100) - Log aggregation and trace queries
• Service Registry (8500) - Service discovery and health checks

Schema Validation

The CLI uses the platform's official schema from:

platform-services/shared/schema/service_descriptor.py

This ensures service configurations are validated against the same schema used by the deployment controller.

Troubleshooting

Command not found: onex

# Reinstall CLI in editable mode
pip install -e /path/to/onexerp-platform-NEW/onex-cli

# Verify installation
which onex
onex --version

Import errors

The CLI imports schema definitions from the platform. Ensure the platform repository is available:

# The symlink should exist:
ls -la onex-cli/onex/schema/service_descriptor.py
# → points to ../../platform-services/shared/schema/service_descriptor.py

Deployment failures

# Validate service.yml first
onex validate

# Check platform health
onex status --env local

# View deployment logs
onex logs deployment-controller

License

MIT License - See platform repository for details.

Support

• Platform Developers: Update CLI in onexerp-platform-NEW/onex-cli/
• Service Developers: Install CLI via pip install -e ../onexerp-platform-NEW/onex-cli
• Issues: Report in platform repository

Related Documentation

• Platform Architecture
• Service Development Guide
• Deployment Guide
• Request Tracing