Metadata-Version: 2.4
Name: stimulir
Version: 0.1.169
Summary: Stimulir Console CLI — workspaces, API keys, BYOK, usage, inference, lab and compute.
License: Proprietary
Project-URL: Homepage, https://www.stimulir.com
Project-URL: Documentation, https://www.stimulir.com/docs/cli/installation
Project-URL: Changelog, https://github.com/stimulir/stimulir-console/releases
Keywords: stimulir,hybrie,inference,lora,peft,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: httpx>=0.27

# 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](https://typer.tiangolo.com),
[Rich](https://rich.readthedocs.io), and [httpx](https://www.python-httpx.org).

## Install

Once published to PyPI:

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

From this repo (development):

```bash
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:

```bash
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:

```bash
stimulir login --token <supabase-jwt>
```

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

```bash
stimulir whoami
stimulir logout
```

## Select a workspace

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

```bash
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.

```bash
# 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)

```bash
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`.

```bash
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.

```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 for the training loop, including from agent traces:

```bash
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

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

### Inference

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

```bash
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)

```bash
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)

```bash
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

```bash
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:

```bash
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`.
