hypercli-sdk 2026.6.21

Python SDK for HyperCLI - GPU orchestration and HyperAgent API

HyperCLI SDK

Python SDK for HyperCLI - GPU orchestration API.

Installation

pip install hypercli-sdk

Setup

Set your API key:

export HYPER_API_KEY=your_api_key

Or create ~/.hypercli/config:

HYPER_API_KEY=your_api_key

Or pass directly:

client = HyperCLI(api_key="your_api_key")

Usage

from hypercli import HyperCLI

client = HyperCLI()

# Check balance
balance = client.billing.balance()
print(f"Balance: ${balance.total:.2f}")
print(f"Rewards: ${balance.rewards:.2f}")

# List transactions
for tx in client.billing.transactions(limit=10):
    print(f"{tx.transaction_type}: ${tx.amount_usd:.4f}")

# Create a job
job = client.jobs.create(
    image="nvidia/cuda:12.0",
    command="python train.py",
    gpu_type="l40s",
    gpu_count=1,
)
print(f"Job ID: {job.job_id}")
print(f"State: {job.state}")

# List jobs
for job in client.jobs.list():
    print(f"{job.job_id}: {job.state}")

# Get job details
job = client.jobs.get("job_id")

# Get job logs
logs = client.jobs.logs("job_id")

# Get GPU metrics
metrics = client.jobs.metrics("job_id")
for gpu in metrics.gpus:
    print(f"GPU {gpu.index}: {gpu.utilization}% util, {gpu.temperature}°C")

# Cancel a job
client.jobs.cancel("job_id")

# Extend runtime
client.jobs.extend("job_id", runtime=7200)

# Get user info
user = client.user.get()
print(f"User: {user.email}")

HyperAgent API

Use client.agent for discovery and plan metadata, and point the OpenAI SDK at the HyperClaw inference base URL for chat completions:

from hypercli import HyperCLI
from openai import OpenAI

sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="sk-agent")
plans = sdk.agent.plans()
activation = sdk.agent.redeem_grant_code("PROMO123")
renewal = sdk.agent.redeem_grant_code("PROMO123", extend_existing=True)

client = OpenAI(
    api_key="your_hyperagent_api_key",
    base_url="https://api.hypercli.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-v3.1",
    messages=[{"role": "user", "content": "Hello!"}]
)

redeem_grant_code() applies a promo/activation code to the current HyperClaw account and returns the created entitlement. Codes create new entitlements by default; pass extend_existing=True only for renewal/extension behavior.

OpenClaw Agents

OpenClaw uses the generic deployment launch surface. registry_url, registry_auth, sync_root, and sync_enabled are generic deployment options; the OpenClaw helpers only add defaults such as routes, image, and sync_root=/home/node.

agent = client.deployments.create_openclaw(
    name="docs-demo",
    start=True,
    heartbeat={"every": "0m"},  # disable upstream OpenClaw heartbeat runs
    registry_url="git.nedos.co",
    registry_auth={"username": "ci", "password": "token"},
)

heartbeat maps directly to upstream OpenClaw config at config.agents.defaults.heartbeat. Omit it to keep upstream defaults, or pass values such as heartbeat={"every": "1h", "target": "last"}.

Error Handling

from hypercli import HyperCLI, APIError

client = HyperCLI()

try:
    job = client.jobs.get("invalid_id")
except APIError as e:
    print(f"Error {e.status_code}: {e.detail}")

License

MIT