xeroctl CLI
Command-line interface for interacting with Xerotier.ai APIs. Upload models, manage resources, and test endpoints from your terminal.
Overview
xeroctl is the official command-line tool for Xerotier.ai. It provides full access to the Xerotier.ai API for:
| Command | Purpose |
|---|---|
upload |
Upload models (directories or archives) |
models |
List, view, update, delete, and version models |
uploads |
Manage upload sessions |
completions |
View stored chat completions |
responses |
Manage OpenAI Responses API data |
chat |
Test chat completions against endpoints |
Installation
Download the pre-built binary for your platform or build from source.
Pre-built Binaries
Download the latest release from the releases page:
# macOS (Apple Silicon)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-darwin-arm64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
# macOS (Intel)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-darwin-amd64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
# Linux (x86_64)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-linux-amd64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
Build from Source
Requires Swift 6.0 or later:
git clone https://github.com/cloudnull/xerotier-public.git
cd xerotier-public
swift build --product xeroctl -c release
# Binary at .build/release/xeroctl
Verify Installation
xeroctl --version
xeroctl --help
Configuration
Configure xeroctl using environment variables or command-line options.
Environment Variables
| Variable | Description |
|---|---|
XEROTIER_BASE_URL |
API base URL including your project ID |
XEROTIER_API_KEY |
Your API key with appropriate scopes |
Shell Configuration
# Add to ~/.bashrc or ~/.zshrc
export XEROTIER_BASE_URL="https://api.xerotier.ai/proj_ABC123/v1"
export XEROTIER_API_KEY="xero_proj_ABC123_your_api_key"
Command-Line Options
Override environment variables per-command:
xeroctl models list \
--base-url "https://api.xerotier.ai/proj_ABC123/v1" \
--api-key "xero_proj_ABC123_your_api_key"
Upload Command
Upload model directories or archives to Xerotier.ai. The upload mode is automatically detected based on the path.
Upload a Directory
xeroctl upload ./my-model "My Custom Model"
Upload an Archive
Supported formats: .tar, .tar.gz, .tar.bz2
xeroctl upload ./model.tar.gz "Qwen3-0.6B"
Options
| Option | Description |
|---|---|
-v, --verbose |
Show detailed upload progress |
Tip: For large models, use verbose mode to see upload progress for each file or chunk.
Models Command
Manage models in your project.
List Models
# List all models
xeroctl models list
# With extended details
xeroctl models list --extended
# Paginate results
xeroctl models list --limit 10 --offset 20
Get Model Details
xeroctl models get <model-id> --extended
Update Model Metadata
xeroctl models update <model-id> \
--description "Fine-tuned for code generation" \
--architecture "transformer" \
--context-length 8192
Delete a Model
# With confirmation prompt
xeroctl models delete <model-id>
# Skip confirmation
xeroctl models delete <model-id> --force
Model Sharing
# Share to catalog
xeroctl models share <model-id>
# Remove from catalog
xeroctl models unshare <model-id>
Model Versions
# List versions
xeroctl models versions list <model-id>
# Create new version
xeroctl models versions create <model-id> 2.0.0 --notes "Improved accuracy"
# Promote version to latest
xeroctl models versions promote <model-id> 2.0.0
# Rollback to previous version
xeroctl models versions rollback <model-id> 1.0.0
Chat Command
Test chat completions against your endpoints directly from the CLI.
Basic Usage
xeroctl chat --endpoint my-endpoint --message "What is machine learning?"
With System Message
xeroctl chat --endpoint my-endpoint \
--system "You are a helpful coding assistant." \
--message "Write a Python function to sort a list"
Streaming Response
xeroctl chat --endpoint my-endpoint \
--message "Tell me a story" \
--stream
With Parameters
xeroctl chat --endpoint my-endpoint \
--message "Generate creative ideas" \
--max-tokens 500 \
--temperature 0.9 \
--top-p 0.95
Show Usage Statistics
xeroctl chat --endpoint my-endpoint \
--message "Hello" \
--show-usage
Options
| Option | Description |
|---|---|
--endpoint <slug> |
Endpoint slug (required) |
-m, --message <text> |
User message (required) |
--system <text> |
System message for context |
--max-tokens <n> |
Maximum tokens to generate |
--temperature <f> |
Sampling temperature (0.0-2.0) |
--stream |
Stream the response |
--store |
Store the completion |
--show-usage |
Show token usage details |
Examples
Upload and Configure a Model
Bash Script
#!/bin/bash
set -e
# Upload model
xeroctl upload ./my-fine-tuned-model "My Fine-Tuned LLM"
# Get the model ID from the list
MODEL_ID=$(xeroctl models list | grep "My Fine-Tuned" | awk '{print $2}' | head -1)
# Update metadata
xeroctl models update "$MODEL_ID" \
--description "Fine-tuned for customer support" \
--context-length 4096 \
--workload-type "inference"
# Create initial version
xeroctl models versions create "$MODEL_ID" 1.0.0 --notes "Initial release"
echo "Model ready: $MODEL_ID"
Batch Test Multiple Endpoints
Bash Script
#!/bin/bash
ENDPOINTS=("endpoint-prod" "endpoint-staging" "endpoint-dev")
TEST_MESSAGE="What is 2+2?"
for endpoint in "${ENDPOINTS[@]}"; do
echo "Testing $endpoint..."
xeroctl chat --endpoint "$endpoint" --message "$TEST_MESSAGE" --show-usage
echo "---"
done
Export Completions for Analysis
Bash Script
# List recent completions
xeroctl completions list --endpoint my-endpoint --limit 100
# Get specific completion details
xeroctl completions get chatcmpl-abc123 --endpoint my-endpoint
# Get messages from a completion
xeroctl completions messages chatcmpl-abc123 --endpoint my-endpoint
