CLI

Command Reference

Every stimulir command, grouped by what it controls.

Auth & workspaces

Login is a browser device authorization, stimulir login prints a link and a short code, you approve in the console, and the CLI gets a revocable session token in ~/.stimulir/. See Installation for the full flow.

bash
# Device login, prints a link + code, approve in the browser
stimulir login

# Inspect the current session (identity, workspace, expiry)
stimulir whoami

# Log out: clear local credentials, or revoke the server-side token too
stimulir logout
stimulir logout --remote

# Login already sets your active workspace; switch it if you have more than one
stimulir workspace list   # the active workspace is marked
stimulir workspace use <id>

Interactive agent

Launch the AI engineer or attach this machine as a local executor. See Agent for approvals and the one-session-two-bodies model.

bash
# Start an interactive agent session (server-side loop, local execution)
stimulir
stimulir agent "<prompt>"

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

# Attach this machine as the local executor for a session started in the app
stimulir attach [<session-key>]

API keys

Manage hyb_* inference keys for the active workspace. See API Keys for fields and limits.

bash
stimulir keys create --name <name> --env prod|staging|dev
stimulir keys list
stimulir keys revoke <key-id>

BYOK credentials

Attach your own provider keys. See BYOK Credentials for the supported providers.

bash
stimulir byok add --provider openai --label <label>
stimulir byok list
stimulir byok verify <credential-id>
stimulir byok remove <credential-id>

Prompts

Versioned prompts for the active workspace. See Prompts for the version model.

bash
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 from traces and uploads. See Data Assets for the stages and the Lab handoff flow.

bash
stimulir data list
stimulir data list --target eval
stimulir data upload ./dataset.jsonl --stage raw --target eval
stimulir data from-trace <trace-id> --source agent --target eval
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 eval
stimulir data update <asset-id> --name "<name>" --target sft
stimulir data snapshot <asset-id>
stimulir data remove <asset-id>

Usage & billing

bash
# Aggregated usage for the active workspace
stimulir usage --window month --group-by provider

# Month-to-date billing snapshot (tokens, cost, by mode/provider)
stimulir billing snapshot

Inference

bash
# One-shot chat completion; --stream for token streaming
stimulir infer chat "<prompt>" --model <model> [--stream]

# List available models
stimulir models

Fusion

Fan a prompt out to a model panel and stream the judge's answer. See Stimulir Fusion for the panel and judge defaults.

bash
# Default panel (stimulir/fusion); streams the judge's answer
stimulir fusion "your question" [--project <id>] [--no-stream]

# Frontier tier (stimulir/fusion-max)
stimulir fusion "your question" --max

# Custom panel and judge
stimulir fusion "your question" --panel model1,model2 --judge model

Codex App

Configure Codex App to use Stimulir as a custom model provider. See Codex App for the generated config and Responses API contract.

bash
# Configure and open Codex App
stimulir launch codex-app --project <project-id> --model moonshotai/Kimi-K2.7-Code

# Trial the exact config without writing
stimulir launch codex-app --staging --model moonshotai/Kimi-K2.6 --dry-run

# Remove the Stimulir-managed Codex config
stimulir launch codex-app --restore

Lab, training, adapters & evaluation

Training

bash
# Train a classical PEFT LoRA adapter with SFT, the standard supervised route
stimulir lab train sft --family qwen3-4b --lora-rank 16 --epochs 3

# Train a classical PEFT LoRA adapter with GRPO against a verifiable environment
stimulir lab train rl --family qwen3-4b --policy peft-lora --lora-rank 16 --prompts 64

# Doc-to-LoRA context internalization, train the hypernetwork
stimulir lab train d2l --family qwen3-4b --examples 500 --epochs 3

# Manage training jobs
stimulir lab jobs list
stimulir lab jobs get <job-id>
stimulir lab jobs cancel <job-id>

Adapters

Register and version adapters in PEFT Tuning (LoRA); load and unload them at runtime with Hot-swap Inference.

bash
# List registered adapters
stimulir lab adapters list
stimulir lab adapters get <adapter-id>

# Hot-swap adapters in the running runtime
stimulir lab adapters load <adapter-id>
stimulir lab adapters unload <adapter-id>

Projectors

Multimodal projector tuning runs, the third training route. Full guide: Projector Tuning (Multimodal).

bash
# Create a projector run (image via SigLIP, audio via Whisper)
stimulir lab projectors create -m image --stages stage1 --dataset <data-asset-id> -n "vision alignment v1"
stimulir lab projectors create -m audio --stages stage1+2 --lora-rank 16 --lora-alpha 32 --dataset <data-asset-id>

# Inspect and manage runs
stimulir lab projectors list --modality image --status running
stimulir lab projectors get <run-id>
stimulir lab projectors delete <run-id> --yes

Evaluation

See Evaluation for parameters and report fields.

bash
# Durable prompt/data/endpoint eval runs
stimulir lab eval create-run \
  --name "Prompt and data regression" \
  --data-asset-id <asset-id> \
  --prompt <key>:<version|label> \
  --model hybrie-runtime-default \
  --execute
stimulir lab eval runs
stimulir lab eval get <run-id>
stimulir lab eval execute-run <run-id>

# Score a classical PEFT adapter on held-out NIAH
stimulir lab eval adapter --family <family> --adapter-dir <dir>

# Reward evaluation of a policy on a verifiable environment
stimulir lab eval rl --family <family> [--policy base|hypernet|peft-lora] \
  [--checkpoint-dir <dir>] [--tasks N] [--pass-threshold X]

# Needle-In-A-Haystack eval of a D2L hypernet checkpoint
stimulir lab eval niah --family qwen3-4b --checkpoint-dir <dir> --examples 200

Compute

bash
# Browse GPU offers
stimulir compute offers

# Launch instances from an offer
stimulir compute up <offer-id> [--count N]

# Manage running instances
stimulir compute list
stimulir compute status <instance-id>
stimulir compute down <instance-id>

# Manage the compute peer registry
stimulir compute peers list
stimulir compute peers add --grpc-peer <endpoint>
stimulir compute peers remove <peer-id>

Storage

bash
# List objects produced by skills and dedicated tasks (active workspace)
stimulir storage list
stimulir storage list --task-id <task-id>   # filter to one run

# Folders (skill outputs auto-file into a folder named after the skill)
stimulir storage folders

# Get a time-limited signed URL for an object, or delete it
stimulir storage link <object-id> [--expires-in 900] [--download]
stimulir storage delete <object-id>

# Fetch an object by its storage key (e.g. a sandbox run/pipe output_key)
stimulir storage get --key <workspace-id>/dedicated-tasks/<skill>/<hex>/output.bin
stimulir storage get --key <output_key> --output result.bin   # download to a file

Managed skills

bash
# Discover the skills a GitHub repo exposes (SKILL.md files)
stimulir skills discover tosi-n/agentic-frame --ref main

# Import selected skills into this workspace's sandbox (pinned to the commit)
stimulir skills import tosi-n/agentic-frame -p skills/evidence-clip --ref main

# List skills imported into the active workspace
stimulir skills list

Sandbox

bash
# Run an imported skill against a stored input, in an isolated sandbox
stimulir sandbox run evidence-clip \
  --input-key <workspace-id>/inputs/clip.mp4 \
  -P start=1 -P end=4

# Print ONLY the bare output_key, for shell capture:
#   KEY=$(stimulir sandbox run evidence-clip --input-key <key> --output-key-only)
stimulir sandbox run evidence-clip --input-key <key> --output-key-only

# Pipe several skills, each step's output_key feeds the next step's input.
# Per-step params: --step slug:key=value,key2=value2
stimulir sandbox pipe \
  --step privacy-layer \
  --step capture-traces \
  --input-key <workspace-id>/uploads/raw.jsonl

# List past dedicated-task runs
stimulir sandbox list

Tunnel

bash
# One-time: point at your environment's self-hosted frps
stimulir tunnel configure \
  --control-host tunnel-control.stimulir.com \
  --domain tunnel.stimulir.com --token <frp-token>

# Expose a local port at https://<label>.<tunnel-domain>
stimulir tunnel start --port 8080 --label my-tunnel
stimulir tunnel list
stimulir tunnel stop my-tunnel