sference-cli 0.0.1__tar.gz → 0.0.3__tar.gz

{sference_cli-0.0.1 → sference_cli-0.0.3}/.gitignore

@@ -8,3 +8,5 @@ build/
 .venv/
 *.egg
 .pytest_cache/
+cli/.env
+

sference_cli-0.0.3/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: sference-cli
+Version: 0.0.3
+Summary: sference command-line interface
+Requires-Python: >=3.12
+Requires-Dist: sference-sdk>=0.0.3
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install sference-cli
+# or isolated install on PATH:
+uv tool install sference-cli
+# or:
+pipx install sference-cli
+```
+
+Then:
+
+```bash
+sference --help
+```
+
+## Authentication
+
+1. **Interactive (browser):** `sference auth login` — opens the console login page, then prompts for an API key from **Console → API keys**.
+2. **Non-interactive / CI:** `sference auth login --api-key 'sk_...'`
+3. **Environment variable:** `SFERENCE_API_KEY` overrides the saved credential file.
+
+Credentials are stored in `~/.sference/credentials.json` unless `SFERENCE_API_KEY` is set.
+
+Verify the current credential:
+
+```bash
+sference auth me
+sference auth me --json
+```
+
+## Quick examples (batches and streams)
+
+Use a `model` string supported by your sference deployment (for self-hosted stacks, match the model your workers consume).
+
+**Batches**
+
+```bash
+sference batch submit --input-file ./workload.jsonl --model Qwen/Qwen2.5-7B-Instruct --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/Qwen2.5-7B-Instruct --window 24h
+```
+
+**Streams**
+
+```bash
+sference stream create --name "my-stream" --window 24h
+sference stream list
+sference stream submit --stream-id <stream_id> --input-file ./lines.jsonl --model Qwen/Qwen2.5-7B-Instruct
+sference stream status --stream-id <stream_id>
+sference responses tail --stream-id <stream_id>
+```
+
+### cURL: OpenAI-compatible `/v1/responses`
+
+The CLI uses this API for `stream submit` (via `POST /v1/responses`). You can call it directly with the same API key as `sference auth login` (or `SFERENCE_API_KEY`). For self-hosted APIs, set `SFERENCE_BASE_URL` to your API origin.
+
+```bash
+export TOKEN=sk_...   # or: export TOKEN="$SFERENCE_API_KEY"
+
+RID=$(curl -sS -X POST "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses" \
+  -H "X-API-Key: $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "Qwen/Qwen2.5-7B-Instruct",
+    "input": [{"role": "user", "content": "Hello"}],
+    "metadata": {"completion_window": "24h"}
+  }' | jq -r '.id')
+
+curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
+  -H "X-API-Key: $TOKEN"
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `SFERENCE_API_KEY` | API key (or JWT); overrides `~/.sference/credentials.json` |
+| `SFERENCE_BASE_URL` | API base URL (default `https://api.sference.com`) |
+| `SFERENCE_CONSOLE_URL` | Console URL for `auth login` browser step (default `https://console.sference.com`) |
+| `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` | Store an API key (optional `--api-key`, `--console-url`, `--no-browser`) |
+| `sference auth me` | Show current user (`--json` for machine-readable output) |
+
+### 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` must be `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`) |
+
+Global options on most batch commands: `--base-url` (default `https://api.sference.com`).
+
+### Responses (`/v1/responses`)
+
+| Command | Description |
+|---------|-------------|
+| `sference responses create` | Create one response (`--model`, `--content`, optional `--wait`, `--poll-ms`, `--timeout-s`) |
+| `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` |
+
+### 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` `1h` or `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):
+
+```json
+{"custom_id":"req-1","method":"POST","url":"/v1/chat/completions","body":{"model":"Qwen/Qwen3.5-4B","messages":[{"role":"user","content":"hi"}]}}
+```
+
+```json
+{"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:
+
+```bash
+sference batch stream --input-file workload.jsonl > results.jsonl
+```
+
+Content-only JSONL (model supplied globally):
+
+```bash
+sference batch stream --input-file prompts.jsonl --model Qwen/Qwen2.5-7B-Instruct > 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 with **`SFERENCE_STREAM_CACHE`**).
+- Key: **SHA-256** of the raw input file bytes (same bytes ⇒ same key, regardless of path).
+- Stored fields: `batch_id`, `base_url` (must match current `--base-url`), `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):
+
+```bash
+sference batch stream --input-file workload.jsonl --no-cache > results.jsonl
+```
+
+### Polling
+
+- **`--poll-interval`** (default `2`): seconds between `GET /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 `failed` or `cancelled` (results JSONL is still printed when available).
+
+### End-to-end example
+
+```bash
+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`](fixtures/example_batch.jsonl)):
+
+1. **OpenAI-compatible:** each line has `custom_id`, `method`, `url`, and `body` (e.g. chat completions payload with per-line `model`). The CLI `--model` flag is ignored for these lines (a warning may be emitted by the SDK).
+2. **Content-only:** each line is `{"content": "..."}`. Then **`--model` is required** on submit/stream.
+
+---
+
+## Python SDK
+
+The CLI uses the sync **`SferenceClient`** from **`sference-sdk`** (`import sference_sdk`).
+
+For your own code, see **[`../sdk-python/README.md`](../sdk-python/README.md)** for:
+
+- **Batches (sync):** `submit_batch`, `wait_for_completion`, `get_results`
+- **`/v1/responses` (sync):** `create_response`, `get_response` (standalone or `metadata.stream_id` for streams)
+- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_responses_events` / `list_responses_events` for completion tailing (`GET /v1/responses/events`)
+
+That README also documents when to prefer **batches** vs **streams** and includes cURL examples.

sference_cli-0.0.3/README.md

@@ -0,0 +1,223 @@
+# 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
+
+```bash
+pip install sference-cli
+# or isolated install on PATH:
+uv tool install sference-cli
+# or:
+pipx install sference-cli
+```
+
+Then:
+
+```bash
+sference --help
+```
+
+## Authentication
+
+1. **Interactive (browser):** `sference auth login` — opens the console login page, then prompts for an API key from **Console → API keys**.
+2. **Non-interactive / CI:** `sference auth login --api-key 'sk_...'`
+3. **Environment variable:** `SFERENCE_API_KEY` overrides the saved credential file.
+
+Credentials are stored in `~/.sference/credentials.json` unless `SFERENCE_API_KEY` is set.
+
+Verify the current credential:
+
+```bash
+sference auth me
+sference auth me --json
+```
+
+## Quick examples (batches and streams)
+
+Use a `model` string supported by your sference deployment (for self-hosted stacks, match the model your workers consume).
+
+**Batches**
+
+```bash
+sference batch submit --input-file ./workload.jsonl --model Qwen/Qwen2.5-7B-Instruct --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/Qwen2.5-7B-Instruct --window 24h
+```
+
+**Streams**
+
+```bash
+sference stream create --name "my-stream" --window 24h
+sference stream list
+sference stream submit --stream-id <stream_id> --input-file ./lines.jsonl --model Qwen/Qwen2.5-7B-Instruct
+sference stream status --stream-id <stream_id>
+sference responses tail --stream-id <stream_id>
+```
+
+### cURL: OpenAI-compatible `/v1/responses`
+
+The CLI uses this API for `stream submit` (via `POST /v1/responses`). You can call it directly with the same API key as `sference auth login` (or `SFERENCE_API_KEY`). For self-hosted APIs, set `SFERENCE_BASE_URL` to your API origin.
+
+```bash
+export TOKEN=sk_...   # or: export TOKEN="$SFERENCE_API_KEY"
+
+RID=$(curl -sS -X POST "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses" \
+  -H "X-API-Key: $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "Qwen/Qwen2.5-7B-Instruct",
+    "input": [{"role": "user", "content": "Hello"}],
+    "metadata": {"completion_window": "24h"}
+  }' | jq -r '.id')
+
+curl -sS "${SFERENCE_BASE_URL:-https://api.sference.com}/v1/responses/${RID}" \
+  -H "X-API-Key: $TOKEN"
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `SFERENCE_API_KEY` | API key (or JWT); overrides `~/.sference/credentials.json` |
+| `SFERENCE_BASE_URL` | API base URL (default `https://api.sference.com`) |
+| `SFERENCE_CONSOLE_URL` | Console URL for `auth login` browser step (default `https://console.sference.com`) |
+| `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` | Store an API key (optional `--api-key`, `--console-url`, `--no-browser`) |
+| `sference auth me` | Show current user (`--json` for machine-readable output) |
+
+### 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` must be `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`) |
+
+Global options on most batch commands: `--base-url` (default `https://api.sference.com`).
+
+### Responses (`/v1/responses`)
+
+| Command | Description |
+|---------|-------------|
+| `sference responses create` | Create one response (`--model`, `--content`, optional `--wait`, `--poll-ms`, `--timeout-s`) |
+| `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` |
+
+### 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` `1h` or `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):
+
+```json
+{"custom_id":"req-1","method":"POST","url":"/v1/chat/completions","body":{"model":"Qwen/Qwen3.5-4B","messages":[{"role":"user","content":"hi"}]}}
+```
+
+```json
+{"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:
+
+```bash
+sference batch stream --input-file workload.jsonl > results.jsonl
+```
+
+Content-only JSONL (model supplied globally):
+
+```bash
+sference batch stream --input-file prompts.jsonl --model Qwen/Qwen2.5-7B-Instruct > 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 with **`SFERENCE_STREAM_CACHE`**).
+- Key: **SHA-256** of the raw input file bytes (same bytes ⇒ same key, regardless of path).
+- Stored fields: `batch_id`, `base_url` (must match current `--base-url`), `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):
+
+```bash
+sference batch stream --input-file workload.jsonl --no-cache > results.jsonl
+```
+
+### Polling
+
+- **`--poll-interval`** (default `2`): seconds between `GET /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 `failed` or `cancelled` (results JSONL is still printed when available).
+
+### End-to-end example
+
+```bash
+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`](fixtures/example_batch.jsonl)):
+
+1. **OpenAI-compatible:** each line has `custom_id`, `method`, `url`, and `body` (e.g. chat completions payload with per-line `model`). The CLI `--model` flag is ignored for these lines (a warning may be emitted by the SDK).
+2. **Content-only:** each line is `{"content": "..."}`. Then **`--model` is required** on submit/stream.
+
+---
+
+## Python SDK
+
+The CLI uses the sync **`SferenceClient`** from **`sference-sdk`** (`import sference_sdk`).
+
+For your own code, see **[`../sdk-python/README.md`](../sdk-python/README.md)** for:
+
+- **Batches (sync):** `submit_batch`, `wait_for_completion`, `get_results`
+- **`/v1/responses` (sync):** `create_response`, `get_response` (standalone or `metadata.stream_id` for streams)
+- **Async:** **`AsyncSferenceClient`** — same surface as sync with `await`, plus `iter_responses_events` / `list_responses_events` for completion tailing (`GET /v1/responses/events`)
+
+That README also documents when to prefer **batches** vs **streams** and includes cURL examples.

{sference_cli-0.0.1 → sference_cli-0.0.3}/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "sference-cli"
-version = "0.0.1"
+version = "0.0.3"
 description = "sference command-line interface"
+readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "typer>=0.24.1",
-    "sference-sdk>=0.1.0",
+    "sference-sdk>=0.0.3",
 ]
 
 [project.scripts]
@@ -19,4 +20,4 @@ build-backend = "hatchling.build"
 packages = ["sference_cli"]
 
 [tool.hatch.build.targets.sdist]
-include = ["sference_cli"]
+include = ["sference_cli", "README.md"]

{sference_cli-0.0.1 → sference_cli-0.0.3}/sference_cli/main.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 import sys
 import time
@@ -18,14 +19,18 @@ from . import stream_cache as stream_cache_mod
 
 _T = TypeVar("_T")
 
+_logger = logging.getLogger(__name__)
+
 
 app = typer.Typer(help="sference CLI", invoke_without_command=True)
 auth_app = typer.Typer(help="Auth commands", invoke_without_command=True)
 batch_app = typer.Typer(help="Batch commands", invoke_without_command=True)
 stream_app = typer.Typer(help="Stream commands", invoke_without_command=True)
+responses_app = typer.Typer(help="Responses commands", invoke_without_command=True)
 app.add_typer(auth_app, name="auth")
 app.add_typer(batch_app, name="batch")
 app.add_typer(stream_app, name="stream")
+app.add_typer(responses_app, name="responses")
 
 CREDENTIALS_PATH = Path.home() / ".sference" / "credentials.json"
 
@@ -52,6 +57,12 @@ def _read_token() -> str | None:
 
 
 def _client(base_url: Optional[str] = None) -> SferenceClient:
+    # If the caller didn't explicitly pass --base-url, allow SFERENCE_BASE_URL
+    # to override the default.
+    env_base_url = os.environ.get("SFERENCE_BASE_URL")
+    if env_base_url and (base_url is None or base_url == "https://api.sference.com"):
+        _logger.info(f"Using SFERENCE_BASE_URL: {env_base_url}")
+        base_url = env_base_url
     return SferenceClient(base_url=base_url, api_key=_read_token())
 
 
@@ -121,6 +132,26 @@ def _print(value: object, as_json: bool) -> None:
         typer.echo(value)
 
 
+def _wait_for_response(
+    client: SferenceClient, response_id: str, *, poll_ms: int, timeout_s: int
+) -> Any:
+    """Poll GET /v1/responses/{id} until terminal status or timeout."""
+    deadline = time.time() + max(1, timeout_s)
+    last: Any = None
+    while True:
+        last = _call_api(lambda: client.get_response(response_id))
+        if hasattr(last, "model_dump"):
+            d = last.model_dump()
+            status = d.get("status") if isinstance(d, dict) else None
+        else:
+            status = getattr(last, "status", None)
+        if status in ("completed", "failed", "cancelled"):
+            return last
+        if time.time() >= deadline:
+            return last
+        time.sleep(max(10, poll_ms) / 1000.0)
+
+
 def _mvp_batch_window_only(value: str) -> str:
     if value != "24h":
         raise typer.BadParameter('Only "24h" is supported in MVP.', param_hint="--window")
@@ -165,6 +196,14 @@ def _stream_root(ctx: typer.Context) -> None:
         raise typer.Exit(code=0)
 
 
+@responses_app.callback()
+def _responses_root(ctx: typer.Context) -> None:
+    """Print help when invoked without a command."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
 @auth_app.command("login")
 def auth_login(
     api_key: Optional[str] = typer.Option(
@@ -172,6 +211,12 @@ def auth_login(
         "--api-key",
         help="API key (sk_...) or JWT. Non-interactive: saves immediately (e.g. CI).",
     ),
+    as_json: bool = typer.Option(False, "--json", help="Print authenticated user as JSON after validation."),
+    validate: bool = typer.Option(
+        True,
+        "--validate/--no-validate",
+        help="Validate the credential by calling GET /v1/auth/me and print the authenticated user.",
+    ),
     console_url: Optional[str] = typer.Option(
         None,
         "--console-url",
@@ -188,6 +233,16 @@ def auth_login(
             raise typer.Exit(code=1)
         _write_token(key)
         typer.echo(f"Credentials saved to {CREDENTIALS_PATH}")
+        if validate:
+            client = _client(None)
+            me = _call_api(client.get_me)
+            if as_json:
+                _print(me, True)
+            else:
+                if isinstance(me, dict) and "username" in me and "role" in me:
+                    typer.echo(f"Authenticated as {me['username']} ({me['role']}).")
+                else:
+                    typer.echo(f"Authenticated. {me}")
         return
 
     base = (console_url or DEFAULT_CONSOLE_URL).rstrip("/")
@@ -213,6 +268,16 @@ def auth_login(
         raise typer.Exit(code=1)
     _write_token(token.strip())
     typer.echo(f"Credentials saved to {CREDENTIALS_PATH}")
+    if validate:
+        client = _client(None)
+        me = _call_api(client.get_me)
+        if as_json:
+            _print(me, True)
+        else:
+            if isinstance(me, dict) and "username" in me and "role" in me:
+                typer.echo(f"Authenticated as {me['username']} ({me['role']}).")
+            else:
+                typer.echo(f"Authenticated. {me}")
 
 
 @auth_app.command("me")
@@ -226,6 +291,113 @@ def auth_me(
     _print(me, as_json)
 
 
+@responses_app.command("create")
+def responses_create(
+    model: str = typer.Option(..., "--model"),
+    content: str = typer.Option(..., "--content"),
+    wait: bool = typer.Option(False, "--wait/--no-wait"),
+    poll_ms: int = typer.Option(500, "--poll-ms", help="Polling interval when --wait is enabled."),
+    timeout_s: int = typer.Option(60, "--timeout-s", help="Timeout in seconds when --wait is enabled."),
+    base_url: str = typer.Option("https://api.sference.com"),
+) -> None:
+    _ensure_api_credential()
+    client = _client(base_url)
+    resp = _call_api(
+        lambda: client.create_response(model=model, input=[{"role": "user", "content": content}])
+    )
+    if wait:
+        final = _wait_for_response(client, resp.id, poll_ms=poll_ms, timeout_s=timeout_s)
+        if getattr(final, "status", None) not in ("completed", "failed", "cancelled"):
+            _print(final.model_dump(), True)
+            raise typer.Exit(code=1)
+        resp = final
+    _print(resp.model_dump(), True)
+
+
+@responses_app.command("result")
+def responses_result(
+    id: str = typer.Option(..., "--id"),
+    poll_ms: int = typer.Option(500, "--poll-ms", help="Polling interval while waiting for completion."),
+    base_url: str = typer.Option("https://api.sference.com"),
+) -> None:
+    """Wait for a response to reach a terminal status and print the final JSON.
+
+    Use Ctrl-C to stop waiting.
+    """
+    _ensure_api_credential()
+    client = _client(base_url)
+    try:
+        while True:
+            resp = _call_api(lambda: client.get_response(id))
+            d = resp.model_dump()
+            status = d.get("status") if isinstance(d, dict) else None
+            if status in ("completed", "failed", "cancelled"):
+                _print(d, True)
+                return
+            time.sleep(max(10, poll_ms) / 1000.0)
+    except KeyboardInterrupt:
+        raise typer.Exit(code=130) from None
+
+
+@responses_app.command("tail")
+def responses_tail(
+    stream_id: Optional[str] = typer.Option(
+        None,
+        "--stream-id",
+        help="Optional stream UUID; omit to tail non-stream completion events only.",
+    ),
+    consumer: str = typer.Option("default", "--consumer", help="Checkpoint namespace for resume."),
+    from_latest: bool = typer.Option(
+        False,
+        "--from-latest",
+        help="Ignore saved checkpoint and start from the latest events page.",
+    ),
+    no_checkpoint: bool = typer.Option(False, "--no-checkpoint", help="Do not read or write checkpoints."),
+    poll_ms: int = typer.Option(5000, "--poll-ms", help="Long-poll wait_ms when catching up (max 30000)."),
+    base_url: str = typer.Option("https://api.sference.com"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    """Print completion events as JSONL (GET /v1/responses/events). Ctrl-C to stop.
+
+    Omit --stream-id for standalone/batch completions; pass --stream-id to scope to a stream.
+    """
+    _ = as_json
+    _ensure_api_credential()
+    client = _client(base_url)
+    bu = base_url.rstrip("/")
+    ck = stream_id if stream_id else "__responses_events__"
+
+    if from_latest and not no_checkpoint:
+        clear_checkpoint(bu, ck, consumer)
+
+    last: str | None = None
+    if not no_checkpoint and not from_latest:
+        last = load_checkpoint(bu, ck, consumer)
+
+    try:
+        while True:
+
+            def fetch() -> Any:
+                return client.list_responses_events(
+                    stream_id=stream_id,
+                    limit=50,
+                    starting_after=last,
+                    wait_ms=min(poll_ms, 30000),
+                )
+
+            page = _call_api(fetch)
+            if not page.data:
+                time.sleep(max(1, poll_ms) / 1000.0)
+                continue
+            for ev in page.data:
+                typer.echo(json.dumps(ev.model_dump(), default=str))
+                last = ev.completion_id
+                if not no_checkpoint:
+                    save_checkpoint(bu, ck, consumer, ev.completion_id)
+    except KeyboardInterrupt:
+        typer.echo("Interrupted.", err=True)
+        raise typer.Exit(code=130) from None
+
 @batch_app.command("list")
 def batch_list(
     base_url: str = typer.Option("https://api.sference.com"),
@@ -519,7 +691,8 @@ def stream_submit(
             typer.echo(f"Unrecognized line format: {line[:100]}", err=True)
             raise typer.Exit(code=1)
 
-        resp = _call_api(lambda: client.create_response(body))
+        # SDK signature is keyword-only; pass the payload as kwargs.
+        resp = _call_api(lambda: client.create_response(**body))
         created_responses.append(resp)
 
     # Return stream detail-like response for compatibility
@@ -556,58 +729,6 @@ def stream_cancel(
     _print(st.model_dump(), as_json)
 
 
-@stream_app.command("tail")
-def stream_tail(
-    stream_id: str = typer.Option(..., "--stream-id"),
-    consumer: str = typer.Option("default", "--consumer", help="Checkpoint namespace for resume."),
-    from_latest: bool = typer.Option(
-        False,
-        "--from-latest",
-        help="Ignore saved checkpoint and start from the latest events page.",
-    ),
-    no_checkpoint: bool = typer.Option(False, "--no-checkpoint", help="Do not read or write checkpoints."),
-    poll_ms: int = typer.Option(5000, "--poll-ms", help="Long-poll wait_ms when catching up (max 30000)."),
-    base_url: str = typer.Option("https://api.sference.com"),
-    as_json: bool = typer.Option(False, "--json"),
-) -> None:
-    """Print stream result events as JSONL (stdout). Checkpoints after each event unless --no-checkpoint."""
-    _ = as_json
-    _ensure_api_credential()
-    client = _client(base_url)
-    bu = base_url.rstrip("/")
-
-    if from_latest and not no_checkpoint:
-        clear_checkpoint(bu, stream_id, consumer)
-
-    last: str | None = None
-    if not no_checkpoint and not from_latest:
-        last = load_checkpoint(bu, stream_id, consumer)
-
-    try:
-        while True:
-
-            def fetch() -> Any:
-                return client.list_stream_events(
-                    stream_id,
-                    limit=50,
-                    starting_after=last,
-                    wait_ms=min(poll_ms, 30000),
-                )
-
-            page = _call_api(fetch)
-            if not page.data:
-                time.sleep(max(1, poll_ms) / 1000.0)
-                continue
-            for ev in page.data:
-                typer.echo(json.dumps(ev.model_dump(), default=str))
-                last = ev.completion_id
-                if not no_checkpoint:
-                    save_checkpoint(bu, stream_id, consumer, ev.completion_id)
-    except KeyboardInterrupt:
-        typer.echo("Interrupted.", err=True)
-        raise typer.Exit(code=130) from None
-
-
 @batch_app.command("download-results")
 def batch_download_results(
     batch_id: str = typer.Option(..., "--batch-id"),

sference_cli-0.0.1/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.4
-Name: sference-cli
-Version: 0.0.1
-Summary: sference command-line interface
-Requires-Python: >=3.12
-Requires-Dist: sference-sdk>=0.1.0
-Requires-Dist: typer>=0.24.1