stimulir 0.1.176

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.

Python SDK

For application or backend code, add the package to that project's runtime environment instead of installing it as an isolated CLI tool:

uv add stimulir

Then import the SDK from the public package:

import os

from stimulir import StimulirClient

client = StimulirClient(
    api_base=os.getenv("STIMULIR_API_BASE", "https://api.stimulir.com"),
    api_key=os.environ["STIMULIR_API_KEY"],  # hyb_...
)

The hyb_* key is the normal customer/runtime auth path. Stimulir derives the workspace and allowed platform scope from the key, so application code does not need to pass a workspace id for normal prompt, data, eval, or inference calls.

Login

stimulir login uses a browser-based device authorization — no password is ever typed in the terminal. It prints a link and a short code, you approve in the console, and the CLI receives a revocable stim_cli_ token:

stimulir login
# 1. CLI prints a link + a short user_code, e.g.
#      Go to https://console.stimulir.com/cli and confirm it shows: ABCD-1234
# 2. Approve in the browser (already signed in) — confirm the code, pick a workspace
# 3. CLI receives an opaque stim_cli_ token, stored in
#    ~/.stimulir/credentials.json (0600), with the workspace pre-selected

stimulir login --device is the explicit form of the same flow.

The stim_cli_ token is opaque, revocable, non-refreshable, with a 30-day TTL, pinned to your user and the workspace you selected. To rotate it, just log in again. A 401 from the server means the token expired or was revoked — re-run stimulir login.

(Non-production environments can override the API/auth endpoints via STIMULIR_API_BASE env var or ~/.stimulir/config.json.)

Already have a token from the console web app? Paste it as an escape hatch:

stimulir login --token <token>

Inspect or end your session with:

stimulir whoami           # opaque token: shows local email + prefix, plus
                          # server-confirmed identity, workspace, and expiry
stimulir logout           # clears the local credentials file
stimulir logout --remote  # revokes the server-side token, then clears locally

Select a workspace

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

stimulir workspace list
stimulir workspace use <workspace-id>

Commands

Agent — the AI engineer in your terminal

Bare stimulir (no subcommand, in a TTY) launches the interactive Stimulir agent against the active workspace. The agent runs server-side (Pi through code-runtime) and executes its tool intents — bash, file reads/writes, glob search — on your machine, with approval prompts. The conversation lives server-side, so the same session shows up in the Engineering traces panel.

# Start the agent (or pass an opening task)
stimulir
stimulir agent "Add a /health endpoint and wire it into the router"

# Resume an existing session
stimulir agent --session <session-key>

# Attach this machine as the local executor for a session started in the app
# (the chat composer's "Continue in: Local" dropdown)
stimulir attach [<session-key>]

Approvals stay on your machine — destructive commands (rm -rf, sudo, force push, key revocation) always prompt even under an "always allow" grant.

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>

Workspace prompts

Versioned prompt management — every save creates a new immutable version, and labels (e.g. prod) move between versions so you can promote or roll back without editing application code.

stimulir prompts list
stimulir prompts get <key> [--label prod|--version N]
stimulir prompts versions <key>
stimulir prompts create --key <key> --file ./prompt.md --label prod --notes "<change notes>"
stimulir prompts update <key> <version> --notes "<change notes>"
stimulir prompts archive <key> <version>
stimulir prompts label <key> <version> <label>

Data assets

Curate datasets for the training loop, including from agent traces:

stimulir data list
stimulir data upload ./dataset.jsonl --stage raw --target sft
stimulir data from-trace <trace-id> --source agent --target sft
stimulir data stage <asset-id> <raw|cleaning|clean_view|snapshot|lab>
stimulir data unstage <asset-id>
stimulir data bulk-stage --ids <asset-id>,<asset-id> --stage lab --target sft
stimulir data update <asset-id> --name "<name>" --target sft
stimulir data snapshot <asset-id>
stimulir data remove <asset-id>

The typical flow is from-trace → stage … lab → snapshot — turn an agent run into staged data, promote it, then pin a snapshot a training run consumes.

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 runs
stimulir lab eval get <run-id>
stimulir lab eval create-run --data-asset-id <asset-id> --prompt <key>:<version|label> --execute
stimulir lab eval execute-run <run-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)	api_key, cli_token (opaque stim_cli_ from device login), optional access_token, refresh_token, expires_at, email

Common environment overrides: STIMULIR_API_BASE, STIMULIR_API_KEY, SUPABASE_URL, SUPABASE_ANON_KEY. Use stimulir workspace use <id> to persist the active CLI workspace.