sference CLI
Command-line interface for the sference batch API (sference). It uses the Python SDK (sference-sdk) and is published on PyPI as sference-cli.
Installation
# One-line install (macOS / Linux)
eval "$(curl -fsSL https://raw.githubusercontent.com/s-ference/sference/main/install.sh)"
Or install from PyPI:
uv tool install sference-cli
Fallback:
pip install sference-cli
# or:
pipx install sference-cli
From a clone of this repo:
uv sync --package sference-cli
uv run sference --help
Then:
sference --help
Authentication
- Interactive (browser):
sference auth loginsigns in with the OAuth 2.0 device flow (RFC 8628). The CLI opens the console approval page and shows a short code; confirm it matches, approve the device, and the CLI finishes on its own. No API key is involved. Pass--no-browseron a remote or headless machine to print the URL and code instead. - Non-interactive / CI:
sference auth login --api-key 'sk_...'saves an API key from Console → API keys without opening a browser. - Environment variable:
SFERENCE_API_KEYoverrides the saved credential file.
Credentials are stored in ~/.sference/credentials.json unless SFERENCE_API_KEY is set. A device login stores a 24 h access token and a 30 d rotating refresh token; the CLI refreshes the access token automatically when you run a command, and sference launch claude also refreshes it mid-session through its proxy. Codex, opencode, and Pi sessions run on the token issued at launch. Signed-in devices are listed, and can be revoked, under Profile → Signed-in devices in the console.
For local development, --base-url (or SFERENCE_BASE_URL) points the device flow at another API and --console-url (or SFERENCE_CONSOLE_URL) overrides the approval page the browser opens.
Verify the current credential:
sference auth me
sference auth me --json
Quick examples (batches and streams)
Use a model string supported by your sference deployment.
Batches
sference batch submit --input-file ./workload.jsonl --model Qwen/Qwen3.6-35B-A3B --window 24h
sference batch status --batch-id <batch_id>
sference batch wait --batch-id <batch_id>
sference batch results --batch-id <batch_id>
sference batch download-results --batch-id <batch_id> --out ./out.jsonl
# Submit, wait, print JSONL results on stdout (stderr: progress; resumable cache)
sference batch stream --input-file ./workload.jsonl --model Qwen/Qwen3.6-35B-A3B --window 24h
Streams
sference stream create --name "my-stream" --window 24h
sference stream list
sference stream submit --stream-id <stream_id> --input-file ./lines.jsonl --model Qwen/Qwen3.6-35B-A3B
sference stream status --stream-id <stream_id>
sference responses tail --stream-id <stream_id>
Environment variables
| Variable | Purpose |
|---|---|
SFERENCE_API_KEY |
API key (or access token); overrides ~/.sference/credentials.json |
SFERENCE_CONSOLE_URL |
Console URL the device-flow approval page opens on (default: server-provided) |
SFERENCE_MODEL |
Default catalog model for sference launch (overrides built-in default) |
SFERENCE_STREAM_CACHE |
Optional path to the stream resumable-cache file (default ~/.sference/stream_cache.json) |
SFERENCE_STREAM_CHECKPOINTS |
Optional path for responses tail event checkpoints (default ~/.sference/stream_checkpoints.json) |
Commands
Auth
| Command | Description |
|---|---|
sference auth login |
Sign in with the browser device flow (--no-browser prints the URL and code; --api-key saves an API key for CI) |
sference auth me |
Show current user (--json for machine-readable output) |
Launch
sference launch claude
sference launch claude points Claude Code at Sference's native /v1/messages endpoint via ANTHROPIC_BASE_URL and enables gateway model discovery: the live catalog is primed into Claude Code's picker cache before launch, so /model lists every Sference model the account can serve. No proxy, no mitmproxy.
| Command | Description |
|---|---|
sference launch claude |
Launch Claude Code against Sference; catalog primed into /model |
sference launch claude --dry-run |
Print the env config + command without launching |
sference launch claude --model zai-org/GLM-5.2 |
Pin a different default model |
sference launch claude --models a,b |
Override the primed picker set (default: live GET /v1/models) |
sference launch claude --enable-tool-search |
Set ENABLE_TOOL_SEARCH=true |
sference launch claude -- --model zai-org/GLM-5.2 -p "hi" |
Forward Claude Code flags/args after -- |
Requires only the Claude Code CLI. Device-flow credentials are refreshed at launch so long sessions start on a fresh 24 h token. --no-anthropic and --proxy-port are accepted as deprecated no-ops for older scripts.
sference launch pi
| Command | Description |
|---|---|
sference launch pi |
Launch Pi with Sference API routing (writes ~/.pi/agent/models.json) |
sference launch pi --dry-run |
Print provider config and command without launching Pi |
sference launch pi --model moonshotai/Kimi-K2.7-Code |
Override catalog model |
sference launch pi -- /path/to/project |
Forward Pi args after sference launch pi |
Requires the Pi CLI on PATH. Writes a sference provider block to ~/.pi/agent/models.json using pi's openai-responses API (the Sference /v1/responses endpoint) with baseUrl, apiKey, and the full list of Sference-provided models (fetched live from GET /v1/models), then execs pi --provider sference --model <id> --models sference/**. The --models sference/** flag scopes pi's /model picker (and Ctrl+P cycling) to Sference models only, so other configured providers are hidden by default (** is required because Sference model ids contain a slash and * would match nothing). All catalog models appear in the picker; --model selects the active one. Reasoning is driven by pi's native reasoning.effort (no per-model thinking-format config needed). If the catalog fetch fails (offline), only the chosen model is registered. Uses ~/.sference/credentials.json or SFERENCE_API_KEY. Default model: moonshotai/Kimi-K2.7-Code (override with --model or SFERENCE_MODEL).
sference launch codex
| Command | Description |
|---|---|
sference launch codex |
Launch the Codex CLI against Sference's /v1/responses |
sference launch codex --dry-run |
Print provider config and command without launching Codex |
sference launch codex --model moonshotai/Kimi-K3 |
Override catalog model |
sference launch codex -- exec "fix the bug" |
Forward Codex args (here: non-interactive codex exec) |
sference launch codex -- -c model_reasoning_effort=high |
Override the reasoning effort (default medium) |
Requires codex on PATH. The sference model provider is passed as codex -c overrides, so ~/.codex/config.toml is never modified and your normal Codex sessions are unaffected; the API key reaches Codex through the SFERENCE_API_KEY env var, never on disk. The launcher disables Codex's hosted web_search tool (Sference's /v1/responses serves function tools, including Codex's namespace tool groups, but no hosted tools) and sets model_context_window from the live catalog so auto-compaction triggers at the model's real limit.
Sub-agents and MCP servers work: the Sference provider applies to the whole session, so agents Codex spawns run on Sference too. The launcher also writes ~/.sference/codex/models.json, a Codex model catalog listing only the Sference models, and passes it as model_catalog_json. Without it Codex offers spawn_agent its own OpenAI models, and a sub-agent started on one of them fails. Each entry is built at launch from the catalog bundled with your Codex (codex debug models --bundled), so it always matches your Codex version; if that command is unavailable the launcher warns and starts without the catalog. An agents.default_subagent_model in your Codex config still pins sub-agents to an OpenAI model, which Sference cannot serve (the launcher warns about it).
Batch
| Command | Description |
|---|---|
sference batch list |
List batches (table; --json for raw payload) |
sference batch submit |
Submit a JSONL file (--input-file, optional --model for content-only lines, --window 24h) |
sference batch stream |
Submit, wait, print JSONL results on stdout (see below) |
sference batch status |
Get one batch (--batch-id, --json) |
sference batch wait |
Poll until terminal state (--batch-id, --poll-interval, --timeout, --json) |
sference batch results |
JSON results payload (--batch-id, --json) |
sference batch cancel |
Cancel a batch (--batch-id, --json) |
sference batch download-results |
Download results JSONL to a file (--batch-id, --out, --format jsonl) |
Responses (/v1/responses)
| Command | Description |
|---|---|
sference responses create |
Create one response (--model, --content; --background submits async and returns immediately). The sync default blocks; if the server-side wait times out, the request is cancelled and the command fails — use --background + sference responses result for long requests |
sference responses result |
Poll until terminal state (--id, --poll-ms) |
sference responses tail |
Print completion events as JSONL via GET /v1/responses/events (optional --stream-id to scope to a stream; omit for non-stream completions). Flags: --consumer, --from-latest, --no-checkpoint, --poll-ms |
Decisions (/v1/decisions)
| Command | Description |
|---|---|
sference decisions create |
Answer up to 64 questions about one state in a single realtime call (--model, --questions JSON or @file, and --state text or --state-json JSON / @file / @-). Prints one line per answer; --json prints the full response |
sference decisions create --model Cloudflare/clef \
--state "I was charged twice, please refund me" \
--questions '{"route": {"type": "choice", "criteria": {"billing": "Payments", "support": "Other"}},
"refund": {"type": "noul"}}'
Stream (first-class streams API)
Long-lived streams are separate from batches: you create a stream, submit responses tied to it over time (POST /v1/responses with metadata.stream_id), and consume completion events with cursor-based pagination on GET /v1/responses/events (pass stream_id when scoping to a stream). Authenticate with your secret API key like other /v1 calls.
| Command | Description |
|---|---|
sference stream create |
Create a stream (--name, --window 24h, --json) |
sference stream list |
List streams (--json) |
sference stream status |
Full detail + counters (--stream-id, --json) |
sference stream submit |
Create responses from JSONL via POST /v1/responses per line (metadata.stream_id set automatically; --stream-id, --input-file, --model required for content-only lines) — per line: OpenAI batch-style {custom_id?, method, url, body} or content-only {content} |
sference stream cancel |
Stop accepting new items and stop enqueueing pending work; does not auto-cancel in-flight requests (--stream-id, --json) |
sference stream archive |
Finalize the stream (optional after cancel); no new items (--stream-id, --json) |
Example JSONL lines for stream submit (both accepted):
{"custom_id":"req-1","method":"POST","url":"/v1/chat/completions","body":{"model":"Qwen/Qwen3.6-35B-A3B","messages":[{"role":"user","content":"hi"}]}}
{"content":"hi"}
Streaming batches (batch stream)
Use sference batch stream when you want a single command that submits a JSONL file, waits until the batch finishes, and writes result lines to stdout so you can pipe or redirect them.
Pipe-friendly UX
- Stdout: only the results JSONL (one JSON object per line, same shape as
GET /v1/batches/{id}/results.jsonl). - Stderr: status lines while waiting, e.g.
Batch batch_abc status=running (42s).
Example:
sference batch stream --input-file workload.jsonl > results.jsonl
Content-only JSONL (model supplied globally):
sference batch stream --input-file prompts.jsonl --model Qwen/Qwen3.6-35B-A3B > results.jsonl
Resumable cache
Batches can take a long time. If you interrupt the command (e.g. Ctrl+C) and run it again with the same input file contents, the CLI reuses the cached batch id instead of submitting a duplicate job.
- Cache file:
~/.sference/stream_cache.json(override withSFERENCE_STREAM_CACHE). - Key: SHA-256 of the raw input file bytes (same bytes ⇒ same key, regardless of path).
- Stored fields:
batch_id,created_at. - After results are written to stdout, the entry for that input is removed so the cache does not grow forever.
- If the cached batch no longer exists on the server (404), the cache entry is dropped and a new batch is submitted.
Force a fresh submission (ignore cache):
sference batch stream --input-file workload.jsonl --no-cache > results.jsonl
Polling
--poll-interval(default2): seconds betweenGET /v1/batches/{id}polls. There is no built-in maximum wait time (suited to 24h-style batches).
Exit codes
- 0 — batch status is
completed. - 1 — batch status is
failedorcancelled(results JSONL is still printed when available).
End-to-end example
export SFERENCE_API_KEY=sk_...
sference batch stream --input-file fixtures/example_batch.jsonl --poll-interval 5 > out.jsonl
JSONL input formats
The SDK and CLI accept two line shapes (see also fixtures/example_batch.jsonl):
- OpenAI-compatible envelope: each line has
custom_id,method,url, andbody. The API receives onlycustom_id+ innerbody(method/urlare ignored). Innerbodymay use:- Chat completions:
messages(non-empty array), plus optionaltemperature,max_tokens,tools, … - Responses API:
input(string or message array), optionalinstructions,max_output_tokens, … — normalized to chat format at batch create.
- Chat completions:
- Content-only: each line is
{"content": "..."}. Then--modelis required on submit/stream.
Invalid row bodies return HTTP 400 at create with requests[i] and custom_id in the error message (nothing is enqueued). Do not set background: true inside batch row bodies.
Example Responses-shaped JSONL line:
{"custom_id":"r2","method":"POST","url":"/v1/responses","body":{"model":"Qwen/Qwen3.6-35B-A3B","input":[{"role":"user","content":"hi"}],"max_output_tokens":256}}
Python SDK
The CLI uses the sync SferenceClient from sference-sdk (import sference_sdk).
For your own code, see ../sdk-python/README.md for:
- Batches (sync):
submit_batch,wait_for_completion,get_results /v1/responses(sync):create_response,get_response(standalone ormetadata.stream_idfor streams)- Async:
AsyncSferenceClient— same surface as sync withawait, plusiter_responses_events/list_responses_eventsfor completion tailing (GET /v1/responses/events)
That README also documents ./workload.jsonl input and when to prefer batches vs streams.
Metadata
Release files for sference-cli 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sference_cli-0.4.0.tar.gz | 36.6 kB | With provenance | Details for sference_cli-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sference_cli-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for sference_cli-0.4.0-py3-none-any.whl |
Total release size: 76.9 kB
Release files / sference_cli-0.4.0.tar.gz
| Download URL | sference_cli-0.4.0.tar.gz |
|---|---|
| Size | 36.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b59640c508a140d2e1e5c785935b905f34a6219f4513eaba843502878c33d11c
|
|
BLAKE2b-256 checksum How to use checksums |
8fa2ea08662d7c691745171b741e49c2e16d3afdb74d49fc826297ef0dbda60d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logRelease files / sference_cli-0.4.0-py3-none-any.whl
| Download URL | sference_cli-0.4.0-py3-none-any.whl |
|---|---|
| Size | 40.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d85ebe905b1d3d63e9d5f28b7e8670b302b6dd6ab26db910092cf61c2d4a9c08
|
|
BLAKE2b-256 checksum How to use checksums |
e7afb0715df2fc0968ecc0126dfbb350e45c315e595ad443b552a6612dc99b13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logSecurity for sference-cli 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sference_cli-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.