starcite 0.0.3 → 0.0.5

package/README.md

@@ -33,32 +33,43 @@ bunx starcite --help
 
 ## Requirements
 
-- Your Starcite Cloud instance URL (`https://<your-instance>.starcite.io`)
-- Your Starcite API key
+- Your Starcite API base URL (`https://<your-instance>.starcite.io`, or local/development URL)
+- Your Starcite credentials:
+  - API key (recommended), or
+  - an existing session token for a single session flow
 
 For temporary usage, use `npx starcite` or `bunx starcite` instead of installing globally.
 
+## Auth and Resolution
+
+The CLI resolves auth in this order:
+
+1. `--token`
+2. `STARCITE_API_KEY`
+3. `~/.starcite/credentials.json`
+4. `apiKey` in `~/.starcite/config.json` or `~/.starcite/config.toml`
+
+How token handling is selected:
+
+- `create` requires a service token with tenant context that can mint a session.
+- `append` and `tail`:
+  - If the token is an API key with `auth:issue` scope, the CLI resolves via identity + session creation/binding.
+  - Otherwise, the token is treated as a session token and must match the target `sessionId`.
+- If no `--token` is supplied, stored/ambient credentials are resolved from env/config.
+
 ## Quick Start
 
 ```bash
-starcite init --endpoint https://<your-instance>.starcite.io --api-key <YOUR_API_KEY> --yes
+starcite config set endpoint https://<your-instance>.starcite.io
+starcite config set api-key <YOUR_API_KEY>
 starcite create --id ses_demo --title "Draft contract"
 starcite sessions list --limit 5
 starcite append ses_demo --agent researcher --text "Found 8 relevant cases..."
-starcite append ses_demo --agent drafter --text "Drafted section 2 with clause references."
 starcite tail ses_demo --cursor 0 --limit 1
 ```
 
 ## Cloud Setup
 
-```bash
-starcite init
-starcite config set endpoint https://<your-instance>.starcite.io
-starcite auth login
-```
-
-Non-interactive alternative:
-
 ```bash
 starcite config set endpoint https://<your-instance>.starcite.io
 starcite config set api-key <YOUR_KEY>
@@ -67,7 +78,7 @@ starcite config set api-key <YOUR_KEY>
 ## Global Options
 
 - `-u, --base-url <url>`: Starcite API base URL (highest precedence)
-- `-k, --token <token>`: Starcite API key / service JWT (highest precedence)
+- `-k, --token <key>`: Starcite API key or session token (highest precedence)
 - `--config-dir <path>`: Starcite CLI config directory (defaults to `~/.starcite`)
 - `--json`: machine-readable JSON output
 - `-v, --version`: show CLI version and exit
@@ -99,6 +110,7 @@ starcite version
 ### `create`
 
 Create a session.
+Requires an API key-capable token context (typically with session minting capability).
 
 ```bash
 starcite create --id ses_demo --title "Draft contract" --metadata '{"tenant_id":"acme"}'
@@ -107,6 +119,7 @@ starcite create --id ses_demo --title "Draft contract" --metadata '{"tenant_id":
 ### `sessions list`
 
 List sessions from the API catalog.
+Uses the resolved API credential context.
 
 ```bash
 starcite sessions list
@@ -121,22 +134,6 @@ Useful flags:
 - `--cursor <cursor>`: pagination cursor from previous result
 - `--metadata <json>`: flat JSON object of exact-match metadata filters
 
-### `init`
-
-Initialize config for remote usage.
-
-Behavior:
-
-- writes endpoint to `~/.starcite/config.json`
-- optionally stores API key
-- supports interactive prompts when flags are omitted
-
-Useful flags:
-
-- `--endpoint <url>`: endpoint to store
-- `--api-key <key>`: API key to save
-- `-y, --yes`: skip prompts and use provided values only
-
 ### `config`
 
 Manage local configuration.
@@ -153,18 +150,6 @@ Key aliases accepted by `config set`:
 - producer id: `producer-id`, `producer_id`
 - API key: `api-key`, `api_key`
 
-### `auth`
-
-Manage API key auth.
-
-```bash
-starcite auth login
-starcite auth status
-starcite auth logout
-```
-
-`auth login` supports `--api-key <key>` for non-interactive flows.
-
 ### `up`
 
 Start local Starcite containers through an interactive wizard (Docker required).
@@ -238,6 +223,8 @@ By default the CLI uses `~/.starcite`:
 
 Use `--config-dir <path>` to override the directory for testing or isolated runs.
 
+Note: `credentials.json` contains the saved API key; `config.json`/`config.toml` may contain defaults, and environment/CLI values still take precedence.
+
 ### `tail <sessionId>`
 
 Replay and follow events over WebSocket.
@@ -248,3 +235,12 @@ starcite tail ses_demo --agent drafter --limit 5 --json
 ```
 
 Press `Ctrl+C` to stop.
+
+Useful flags:
+
+- `--cursor <cursor>`: replay cursor (inclusive)
+- `--agent <agent>`: filter to one `agent:<name>`
+- `--limit <count>`: stop after N emitted events
+- `--no-follow`: stop after replay instead of following live events
+
+By default, `tail` starts from cursor `0` and requests batched replay frames from the API for faster catch-up.