stimulir 0.1.165

Stimulir Console CLI — workspaces, API keys, BYOK, usage, inference, lab and compute.

stimulir CLI

Command-line interface for the Stimulir Console platform — workspaces, API keys, BYOK credentials, usage/billing, inference, and HybrIE lab/compute.

Built with Python 3.11+, Typer, Rich, and httpx.

Install

Once published to PyPI:

uv tool install stimulir
stimulir --help
# or run without installing:
uvx stimulir --help

From this repo (development):

uv tool install ./cli          # isolated tool from the local source
# or, for live-editing development:
cd cli && uv venv && uv pip install -e .

Conda/miniconda note: if you use plain pip install -e instead of uv, Anaconda Python builds skip the __editable__.*.pth hook, so the editable install silently fails to import (ModuleNotFoundError: stimulir_cli). uv avoids this entirely.

Login

Log in with your Stimulir account — auth defaults are baked in, nothing to configure:

stimulir login
# prompts for email + password, stores tokens in ~/.stimulir/credentials.json (0600)

(Non-production environments can override the auth endpoint via SUPABASE_URL / SUPABASE_ANON_KEY env vars or ~/.stimulir/config.json.)

Already have a JWT from the console web app? Paste it:

stimulir login --token <supabase-jwt>

Sessions auto-refresh using the stored refresh token. Inspect or end your session with:

stimulir whoami
stimulir logout

Select a workspace

Most commands are scoped to a workspace (business profile):

stimulir workspace list
stimulir workspace use <workspace-id>

Commands

API keys (hyb_* inference keys)

stimulir keys create --name cli --env prod --expires-in-days 90 --save
stimulir keys list --include-revoked
stimulir keys revoke <key-id>

The plaintext key is shown exactly once; --save stores it in ~/.stimulir/credentials.json so stimulir infer can use it.

BYOK provider credentials

Providers: openai, anthropic, google_gemini, mistral, aws_bedrock, azure_openai, together_ai, nebius.

stimulir byok add --provider anthropic --label "prod key"   # secret prompted without echo
stimulir byok list
stimulir byok verify <credential-id>
stimulir byok remove <credential-id>

Usage & billing

stimulir usage --window 30d --group-by model
stimulir billing snapshot

Inference

Uses a hyb_* API key (stimulir keys create --save or STIMULIR_API_KEY):

stimulir infer chat "Summarise IFRS 16 in one paragraph" --model hybrie-mid
stimulir infer chat "Write a haiku about ledgers" --model hybrie-small --stream

HybrIE lab (training + eval)

stimulir lab train sft --family qwen3-4b --lora-rank 8 --examples 500 --epochs 3 --lr 1e-4 --eval-examples 200 --seed 42 --checkpoint-dir runs/sft
stimulir lab train d2l --family qwen3-4b --examples 500 --epochs 3 --lr 1e-4 --eval-examples 200 --seed 42 --checkpoint-dir runs/d2l
stimulir lab train rl --family qwen3-4b --environment niah --prompts 64 --group-size 8 --policy hypernet --lr 1e-5 --kl-beta 0.05
stimulir lab jobs list
stimulir lab jobs get <job-id>
stimulir lab jobs cancel <job-id>
stimulir lab eval niah --family qwen3-4b --checkpoint-dir ~/hybrie-mounts/d2l-artifacts/<job>/checkpoint --examples 200 --seed 42
stimulir lab eval adapter --family qwen3-4b --adapter-dir ~/adapters/invoices-lora --examples 200 --seed 42
stimulir lab eval rl --family qwen3-4b --environment niah --policy hypernet --checkpoint-dir runs/rl/<job> --tasks 50 --pass-threshold 0.8
stimulir lab adapters list
stimulir lab adapters get <adapter-id>
stimulir lab adapters load <adapter-id>
stimulir lab adapters unload <adapter-id>

Compute (GPU offers + instances + peers)

stimulir compute offers
stimulir compute up <offer-id> --count 2
stimulir compute list
stimulir compute status <instance-id>
stimulir compute down <instance-id>
stimulir compute peers list
stimulir compute peers add --name lambda-a100 --grpc http://10.0.0.5:9090 --realtime http://10.0.0.5:8011
stimulir compute peers remove <peer-id>

Models

stimulir models

HybrIE routing

lab, compute, and models go through the console proxy ({api_base}/api/v1/hybrie/*, Supabase JWT + workspace header) by default. To talk to a HybrIE runtime directly, pass --endpoint http://host:port on any of those commands, or persist it in ~/.stimulir/config.json as hybrie_endpoint — requests then hit {endpoint}/v1/*.

Scripting

Every command accepts --json to emit the raw API response:

stimulir keys list --json | jq '.api_keys[].prefix'

Configuration reference

File	Contents
~/.stimulir/config.json	api_base, workspace_id, hybrie_endpoint, supabase_url, supabase_anon_key
~/.stimulir/credentials.json (0600)	access_token, refresh_token, expires_at, email, optional api_key

Environment overrides: STIMULIR_API_BASE, STIMULIR_WORKSPACE_ID, STIMULIR_ACCESS_TOKEN, STIMULIR_API_KEY, SUPABASE_URL, SUPABASE_ANON_KEY.