CLI Reference

Composabl CLI API Documentation

Overview

The Composabl CLI provides command-line tools for managing Composabl 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 Composabl package:

pip install composabl

Verify Installation

# Check CLI is available
composabl --help

# Check version
composabl version

Environment Configuration

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

# Accept EULA
export COMPOSABL_EULA_AGREED=1

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

# Set API endpoint (optional, for custom deployments)
export COMPOSABL_API_URL="https://api.composabl.io"

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

Authentication

Login

Authenticate with Composabl 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
Composabl Version     : 0.0.0
Composabl Core Version: 0.0.0
Composabl Train Version: 0.0.0
Composabl CLI Version : 0.0.0
Composabl 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 COMPOSABL_LICENSE="your-license-key"
export COMPOSABL_EULA_AGREED=1

# API configuration
export COMPOSABL_API_URL="https://api.composabl.io"
export COMPOSABL_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 COMPOSABL_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