# 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](#installation-and-setup)
2. [Authentication](#authentication)
3. [Debug & Version Information](#debug-and-version-information)

### Installation & Setup

#### Installation

The CLI is included with the main AMESA package:

```bash
pip install composabl
```

#### Verify Installation

```bash
# Check CLI is available
composabl --help

# Check version
composabl version
```

#### Environment Configuration

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

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

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

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

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

```bash
# 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
# Bash
composabl --install-completion bash

# Zsh
composabl --install-completion zsh

# Fish
composabl --install-completion fish
```

#### Error Handling

Common errors and solutions:

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

   ```bash
   # Run multiple simulators
   for i in {1..4}; do
     composabl sim start sim-demo &
   done
   wait
   ```
2. **Batch Publishing**

   ```bash
   # Publish all skills
   find skills -name "pyproject.toml" -execdir \
     composabl skill publish . \;
   ```
3. **Resource Optimization**

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

### Troubleshooting

#### Enable Debug Logging

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amesa.com/reference/cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.