CLI Reference

AMESA CLI API Documentation

Overview

The AMESA CLI provides command-line tools for managing AMESA projects, creating components, running simulators, submitting training jobs, and more. It's designed to streamline the development workflow for building autonomous agents.

Table of Contents

1. Installation & Setup

2. Authentication

3. Debug & Version Information

Installation & Setup

Installation

The CLI is included with the main AMESA package:

pip install composabl

Verify Installation

# Check CLI is available
composabl --help

# Check version
composabl version

Environment Configuration

# Set license key
export AMESA_LICENSE="your-license-key"

# Accept EULA
export AMESA_EULA_AGREED=1

# Set log level (optional)
export LOGLEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

# Set API endpoint (optional, for custom deployments)
export AMESA_API_URL="https://api.amesa.com"

# Set environment (optional)
export AMESA_ENV=prod  # prod, stg, dev

Authentication

Login

Authenticate with AMESA services:

# Interactive login (opens browser)
composabl login

The login process:

1. Generates a unique session token

2. Opens your web browser for authentication

3. Saves credentials to ~/.composabl/token

Token Management

# Token locations by environment
~/.composabl/token      # Production
~/.composabl/token_stg  # Staging
~/.composabl/token_dev  # Development

# Manually set token
echo "your-token" > ~/.composabl/token

Debug & Version Information

Show Version

composabl version

# Output:
WRAPPER   : 0.0.0
API       : 0.0.0
CLI       : 0.0.0
CORE      : 0.0.0
TRAIN     : 0.0.0

Show Debug Information

composabl debug

# Output:
Platform              : Linux-5.15.0-1234-generic
Python Version        : 3.11.5
AMESA Version     : 0.0.0
AMESA Core Version: 0.0.0
AMESA Train Version: 0.0.0
AMESA CLI Version : 0.0.0
AMESA API Version : 0.0.0
Is Cython Build       : True
CPU Count             : 16
Memory (GB)           : 32.0
Ray Version           : 2.12.0

Project Structure

Recommended organization:

my-project/
├── agents/
│   ├── temperature-controller/
│   │   └── agent.py
│   └── navigation-agent/
│       └── agent.py
├── skills/
│   ├── maintain-temp/
│   │   ├── pyproject.toml
│   │   └── maintain_temp/
│   │       └── teacher.py
│   └── avoid-obstacles/
│       ├── pyproject.toml
│       └── avoid_obstacles/
│           └── controller.py
├── simulators/
│   └── reactor-sim/
│       ├── pyproject.toml
│       └── reactor_sim/
│           ├── sim.py
│           └── sim_impl.py
├── perceptors/
│   └── sensor-fusion/
│       ├── pyproject.toml
│       └── sensor_fusion/
│           └── perceptor.py
├── selectors/
│   └── mode-selector/
│       ├── pyproject.toml
│       └── mode_selector/
│           └── controller.py
├── configs/
│   ├── training.yaml
│   └── deployment.yaml
└── recordings/
    └── training-runs/

Environment Variables

# Core settings
export AMESA_LICENSE="your-license-key"
export AMESA_EULA_AGREED=1

# API configuration
export AMESA_API_URL="https://api.amesa.com"
export AMESA_ENV=prod  # prod, stg, dev

# Logging
export LOGLEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

# SSL certificates (enterprise)
export SSL_CERT_FILE="/path/to/cert.pem"
export SSL_CERT_PATH="/path/to/certs/"

# Kubernetes (if using)
export KUBECONFIG="/path/to/kubeconfig"

# Docker
export DOCKER_HOST="unix:///var/run/docker.sock"

Shell Completion

Enable tab completion for bash/zsh:

# Bash
composabl --install-completion bash

# Zsh
composabl --install-completion zsh

# Fish
composabl --install-completion fish

Error Handling

Common errors and solutions:

# License error
Error: License validation failed
Solution: export AMESA_LICENSE="your-key"

# Connection error
Error: Failed to connect to simulator
Solution: Check simulator is running with `composabl sim status`

# Import error
Error: No module named 'composabl'
Solution: pip install composabl

# Docker error
Error: Cannot connect to Docker daemon
Solution: Ensure Docker is running and user has permissions

# Out of memory
Error: Ray out of memory
Solution: Reduce num_workers or increase system memory

Performance Tips

1. Parallel Operations

   # Run multiple simulators
   for i in {1..4}; do
     composabl sim start sim-demo &
   done
   wait

2. Batch Publishing

   # Publish all skills
   find skills -name "pyproject.toml" -execdir \
     composabl skill publish . \;

3. Resource Optimization

   # Limit Docker resources
   export DOCKER_MEMORY="4g"
   export DOCKER_CPUS="2"

Troubleshooting

Enable Debug Logging

# Set debug level
export LOGLEVEL=DEBUG

# Run with verbose output
composabl --verbose sim validate

# Save debug output
composabl sim validate 2>&1 | tee debug.log