eightstatecli 0.4.1__tar.gz → 0.4.3__tar.gz

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eightstatecli
-Version: 0.4.1
+Version: 0.4.3
 Summary: Eightstate CLI — unified AI services from the command line
 Project-URL: Homepage, https://github.com/eight-state/eightstate
 Project-URL: Repository, https://github.com/eight-state/eightstate

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eightstatecli"
-version = "0.4.1"
+version = "0.4.3"
 description = "Eightstate CLI — unified AI services from the command line"
 readme = "README.md"
 requires-python = ">=3.10"

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/__init__.py

@@ -17,7 +17,7 @@ AGENT INSTRUCTIONS:
   - Exit codes: 0=success, 1=error, 2=usage
 """
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"
 
 import argparse
 import base64
@@ -718,7 +718,7 @@ config: ~/.escli/config.json (600 permissions, owner-only)
     subs = root.add_subparsers(dest="command", metavar="command")
 
     # ── auth ──────────────────────────────────────────────────────────
-    auth_p = subs.add_parser("auth", aliases=["a"], help="Authentication and profiles", formatter_class=F,
+    auth_p = subs.add_parser("auth", aliases=["a"], help="Manage API auth and profiles", formatter_class=F,
                              epilog=f"""subcommands:
   login    {DOT} authenticate with API key
   logout   {DOT} remove credentials
@@ -733,7 +733,7 @@ agent examples:
 """)
     auth_subs = auth_p.add_subparsers(dest="auth_command", metavar="subcommand")
 
-    login_p = auth_subs.add_parser("login", aliases=["l"], help="Authenticate with an API key", formatter_class=F,
+    login_p = auth_subs.add_parser("login", aliases=["l"], help="Authenticate via browser or API key", formatter_class=F,
                                    epilog=f"""examples:
   escli auth login                    {DOT} interactive prompt
   escli auth login --key sk-xxx       {DOT} non-interactive (agents/CI)
@@ -745,24 +745,24 @@ agent: escli --json auth login --key sk-xxx
 """)
     login_p.add_argument("--key", "-k", default=None, help="API key (omit for interactive prompt)")
     login_p.add_argument("--profile", "-p", default="default", help="Profile name (default: default)")
-    login_p.add_argument("--label", default=None, help="Human-readable label for this profile")
-    login_p.add_argument("--endpoint", default=None, help=f"API endpoint (default: {ENDPOINT})")
+    login_p.add_argument("--label", default=None, help="Profile label")
+    login_p.add_argument("--endpoint", default=None, help="API endpoint")
     login_p.set_defaults(func=cmd_auth_login)
 
     logout_p = auth_subs.add_parser("logout", help="Remove stored credentials")
     logout_p.add_argument("--profile", "-p", default=None, help="Profile to remove (default: active)")
-    logout_p.add_argument("--all", action="store_true", help="Remove ALL profiles")
+    logout_p.add_argument("--all", action="store_true", help="Remove all profiles")
     logout_p.set_defaults(func=cmd_auth_logout)
 
-    auth_subs.add_parser("status", aliases=["s", "whoami"], help="Show current auth status").set_defaults(func=cmd_auth_status)
-    auth_subs.add_parser("profiles", aliases=["ls", "list"], help="List all profiles").set_defaults(func=cmd_auth_profiles)
+    auth_subs.add_parser("status", aliases=["s", "whoami"], help="Show current profile and auth state").set_defaults(func=cmd_auth_status)
+    auth_subs.add_parser("profiles", aliases=["ls", "list"], help="List all stored profiles").set_defaults(func=cmd_auth_profiles)
 
-    switch_p = auth_subs.add_parser("switch", aliases=["use"], help="Switch active profile")
+    switch_p = auth_subs.add_parser("switch", aliases=["use"], help="Switch the active profile")
     switch_p.add_argument("profile_name", help="Profile to activate")
     switch_p.set_defaults(func=cmd_auth_switch)
 
     # ── image ─────────────────────────────────────────────────────────
-    image_p = subs.add_parser("image", aliases=["img", "i"], help="Image generation and editing", formatter_class=F,
+    image_p = subs.add_parser("image", aliases=["img", "i"], help="Generate or edit images from prompts", formatter_class=F,
                               epilog=f"""subcommands:
   generate (gen, g)  {DOT} generate image from text prompt
   edit (e)           {DOT} edit existing image with instruction
@@ -777,29 +777,29 @@ sizes: square(1024x1024) landscape(1536x1024) portrait(1024x1536)
     image_subs = image_p.add_subparsers(dest="image_command", metavar="subcommand")
 
     def add_image_flags(p, include_input=False):
-        p.add_argument("prompt", nargs="+", help="Text prompt describing desired image")
+        p.add_argument("prompt", nargs="+", help="Text prompt")
         p.add_argument("-s", "--size", default=os.environ.get("ESCLI_IMAGE_SIZE", DEFAULTS["size"]),
-                       help="Image size: square|sq|landscape|wide|ls|portrait|tall|port or WxH (default: square = 1024x1024)")
+                       help="Size: sq|wide|tall or WxH (default: 1024x1024)")
         p.add_argument("-q", "--quality", default=os.environ.get("ESCLI_IMAGE_QUALITY", DEFAULTS["quality"]),
-                       choices=VALID_QUALITIES, help="Quality: low (fast, ~15s) | medium (~25s) | high (best, ~40s) (default: high)")
+                       choices=VALID_QUALITIES, help="Quality: low|medium|high (default: high)")
         p.add_argument("-f", "--format", default=os.environ.get("ESCLI_IMAGE_FORMAT", DEFAULTS["format"]),
-                       choices=VALID_FORMATS, help="Output format: png | jpeg | jpg | webp (default: png)")
+                       choices=VALID_FORMATS, help="Format: png|jpeg|webp (default: png)")
         p.add_argument("-m", "--model", default=os.environ.get("ESCLI_IMAGE_MODEL", DEFAULTS["model"]),
-                       help="Model to use (default: gpt-image-2)")
+                       help="Model (default: gpt-image-2)")
         p.add_argument("-o", "--output", default=None,
-                       help="Output file path. If omitted, auto-generates: YYYYMMDD-HHMMSS-slugified-prompt.png")
+                       help="Output path (default: auto-named in --out-dir)")
         p.add_argument("-d", "--out-dir", default=os.environ.get("ESCLI_OUT_DIR", DEFAULTS["out_dir"]),
-                       help="Output directory when -o not set (default: current dir)")
-        p.add_argument("--open", action="store_true", help="Open image in default viewer after generating")
+                       help="Output dir (default: .)")
+        p.add_argument("--open", action="store_true", help="Open result after writing")
         p.add_argument("--compression", type=int, default=None, metavar="0-100",
-                       help="Output compression level for jpeg/webp (0=min, 100=max)")
+                       help="JPEG/WebP compression 0-100")
         p.add_argument("--moderation", default=None, choices=["auto", "low"],
-                       help="Content moderation: auto (default) | low (permissive)")
+                       help="Moderation: auto|low")
         if include_input:
             p.add_argument("-i", "--input", required=True,
-                           help="Path to input image file to edit (png, jpg, webp)")
+                           help="Input image (png/jpg/webp)")
             p.add_argument("--fidelity", default=None, choices=["low", "high"],
-                           help="How closely to preserve the input image: low (more creative) | high (more faithful)")
+                           help="Fidelity to input: low|high")
 
     gen_p = image_subs.add_parser("generate", aliases=["gen", "g"], help="Generate an image from a text prompt",
                                   formatter_class=F, epilog=f"""sizes (any of these work for -s):
@@ -834,7 +834,7 @@ agent examples:
 """)
     add_image_flags(gen_p)
     gen_p.add_argument("--background", default=None, choices=VALID_BACKGROUNDS,
-                       help="Background: auto (default) | transparent (removes background)")
+                       help="Background: auto|transparent")
     gen_p.set_defaults(func=cmd_image_generate)
 
     edit_p = image_subs.add_parser("edit", aliases=["e"], help="Edit an existing image with an instruction",
@@ -863,7 +863,7 @@ supported input formats: png, jpg, jpeg, webp
     edit_p.set_defaults(func=cmd_image_edit)
 
     # ── models ────────────────────────────────────────────────────────
-    subs.add_parser("models", aliases=["m"], help="List available models", formatter_class=F,
+    subs.add_parser("models", aliases=["m"], help="List models available on the endpoint", formatter_class=F,
                     epilog=f"""lists all models available on the API endpoint.
 
 agent example:
@@ -896,7 +896,7 @@ agent example:
     register_usage(subs)
 
     # ── version ───────────────────────────────────────────────────────
-    subs.add_parser("version", help="Show version info").set_defaults(func=cmd_version)
+    subs.add_parser("version", help="Print escli version").set_defaults(func=cmd_version)
 
     return root
 

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/audio.py

@@ -394,7 +394,7 @@ def register(subparsers):
     F = argparse.RawDescriptionHelpFormatter
 
     audio_p = subparsers.add_parser(
-        "audio", aliases=["au"], help="Audio transcription (AssemblyAI)",
+        "audio", aliases=["au"], help="Transcribe audio files or URLs",
         formatter_class=F,
         epilog="""subcommands:
   transcribe <file-or-url>    Transcribe audio with speaker diarization
@@ -413,42 +413,42 @@ examples:
     audio_subs = audio_p.add_subparsers(dest="audio_command", metavar="subcommand")
 
     # transcribe
-    tr_p = audio_subs.add_parser("transcribe", aliases=["t"], help="Transcribe audio")
+    tr_p = audio_subs.add_parser("transcribe", aliases=["t"], help="Transcribe an audio file or URL")
     tr_p.add_argument("source", help="Audio file path or URL")
-    tr_p.add_argument("-o", "--output", default=None, help="Write output to file")
-    tr_p.add_argument("--format", choices=["text", "json", "srt", "vtt"], default="text", help="Output format")
+    tr_p.add_argument("-o", "--output", default=None, help="Output file")
+    tr_p.add_argument("--format", choices=["text", "json", "srt", "vtt"], default="text", help="Output format: text|json|srt|vtt")
     # Speaker diarization
-    tr_p.add_argument("--speakers", action="store_true", help="Enable speaker labels")
+    tr_p.add_argument("--speakers", action="store_true", help="Speaker diarization")
     tr_p.add_argument("--speakers-expected", type=int, default=None, metavar="N", help="Expected speaker count (1-20)")
-    tr_p.add_argument("--speaker-names", default=None, metavar="A,B,C", help="Identify speakers by name")
+    tr_p.add_argument("--speaker-names", default=None, metavar="A,B,C", help="Identify speakers by name (comma-separated)")
     # Audio intelligence
-    tr_p.add_argument("--sentiment", action="store_true", help="Enable sentiment analysis")
-    tr_p.add_argument("--chapters", action="store_true", help="Enable auto chapters")
-    tr_p.add_argument("--entities", action="store_true", help="Enable entity detection")
-    tr_p.add_argument("--summarize", action="store_true", help="Enable summarization")
-    tr_p.add_argument("--highlights", action="store_true", help="Enable auto highlights")
-    tr_p.add_argument("--topics", action="store_true", help="Enable topic detection (IAB)")
-    tr_p.add_argument("--content-safety", action="store_true", help="Enable content safety detection")
+    tr_p.add_argument("--sentiment", action="store_true", help="Sentiment analysis")
+    tr_p.add_argument("--chapters", action="store_true", help="Auto chapters")
+    tr_p.add_argument("--entities", action="store_true", help="Entity detection")
+    tr_p.add_argument("--summarize", action="store_true", help="Summarization")
+    tr_p.add_argument("--highlights", action="store_true", help="Auto highlights")
+    tr_p.add_argument("--topics", action="store_true", help="IAB topic detection")
+    tr_p.add_argument("--content-safety", action="store_true", help="Content safety detection")
     # Transcription options
     tr_p.add_argument("--language", default=None, metavar="CODE", help="Language code (default: auto-detect)")
     tr_p.add_argument("--dual-channel", action="store_true", help="Dual channel transcription")
     tr_p.add_argument("--multichannel", action="store_true", help="Multichannel transcription")
-    tr_p.add_argument("--word-boost", default=None, metavar="W1,W2", help="Boost accuracy for words")
+    tr_p.add_argument("--word-boost", default=None, metavar="W1,W2", help="Boost accuracy for words (comma-separated)")
     tr_p.add_argument("--disfluencies", action="store_true", help="Include filler words")
     tr_p.add_argument("--filter-profanity", action="store_true", help="Filter profanity")
     tr_p.add_argument("--redact-pii", action="store_true", help="Redact PII")
     tr_p.set_defaults(func=cmd_transcribe)
 
     # status
-    st_p = audio_subs.add_parser("status", aliases=["s"], help="Check transcript status")
+    st_p = audio_subs.add_parser("status", aliases=["s"], help="Check transcript job status")
     st_p.add_argument("transcript_id", help="Transcript ID")
     st_p.set_defaults(func=cmd_status)
 
     # get
-    get_p = audio_subs.add_parser("get", aliases=["g"], help="Fetch completed transcript")
+    get_p = audio_subs.add_parser("get", aliases=["g"], help="Fetch a completed transcript")
     get_p.add_argument("transcript_id", help="Transcript ID")
-    get_p.add_argument("--format", choices=["text", "json", "srt", "vtt"], default="text", help="Output format")
-    get_p.add_argument("-o", "--output", default=None, help="Write output to file")
+    get_p.add_argument("--format", choices=["text", "json", "srt", "vtt"], default="text", help="Output format: text|json|srt|vtt")
+    get_p.add_argument("-o", "--output", default=None, help="Output file")
     get_p.set_defaults(func=cmd_get)
 
     # list

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/docs.py

@@ -333,7 +333,7 @@ def register(subparsers):
     F = argparse.RawDescriptionHelpFormatter
 
     docs_p = subparsers.add_parser(
-        "docs", aliases=["d"], help="Library documentation search (Context7)",
+        "docs", aliases=["d"], help="Fetch up-to-date library docs",
         formatter_class=F,
         epilog="""subcommands:
   search <library>                Search for libraries
@@ -350,30 +350,30 @@ examples:
     docs_subs = docs_p.add_subparsers(dest="docs_command", metavar="subcommand")
 
     # search
-    search_p = docs_subs.add_parser("search", aliases=["s"], help="Search for libraries")
-    search_p.add_argument("library_name", help="Library name to search for")
+    search_p = docs_subs.add_parser("search", aliases=["s"], help="Search for libraries by name")
+    search_p.add_argument("library_name", help="Library name")
     search_p.add_argument("query", nargs="?", default=None, help="Optional search query")
-    search_p.add_argument("--limit", type=int, default=10, help="Limit results (default: 10)")
+    search_p.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     search_p.add_argument("--refresh", action="store_true", help="Bypass cache")
     search_p.set_defaults(func=cmd_search)
 
     # get (one-shot: resolve + fetch)
-    get_p = docs_subs.add_parser("get", aliases=["g"], help="Resolve + fetch docs")
+    get_p = docs_subs.add_parser("get", aliases=["g"], help="Resolve a library and fetch docs in one shot")
     get_p.add_argument("library_name", help="Library name")
     get_p.add_argument("query", help="Documentation query")
     get_p.add_argument("--tokens", type=int, default=None, help="Max tokens to return")
     get_p.add_argument("--page", type=int, default=None, help="Page number (1-10)")
-    get_p.add_argument("--topic", default=None, help="Focus on specific topic")
+    get_p.add_argument("--topic", default=None, help="Focus on a topic")
     get_p.add_argument("--refresh", action="store_true", help="Bypass cache")
     get_p.set_defaults(func=cmd_get)
 
     # fetch (by library ID)
-    fetch_p = docs_subs.add_parser("fetch", aliases=["f"], help="Fetch docs by library ID")
+    fetch_p = docs_subs.add_parser("fetch", aliases=["f"], help="Fetch docs by exact library ID")
     fetch_p.add_argument("library_id", help="Library ID (e.g. /facebook/react)")
     fetch_p.add_argument("query", help="Documentation query")
     fetch_p.add_argument("--tokens", type=int, default=None, help="Max tokens to return")
     fetch_p.add_argument("--page", type=int, default=None, help="Page number (1-10)")
-    fetch_p.add_argument("--topic", default=None, help="Focus on specific topic")
+    fetch_p.add_argument("--topic", default=None, help="Focus on a topic")
     fetch_p.add_argument("--refresh", action="store_true", help="Bypass cache")
     fetch_p.set_defaults(func=cmd_fetch)
 

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/research.py

@@ -27,13 +27,27 @@ import urllib.request
 import urllib.error
 from datetime import datetime, timezone
 
-from ..services.credentials import get_key_for_service, call_with_retry, ServiceCallError
+from ..services.credentials import (
+    get_key_for_service,
+    call_with_retry,
+    vend_key,
+    ServiceCallError,
+    CONFIG_DIR,
+)
 
 API_BASE = "https://api.parallel.ai"
 SSE_BETA = "events-sse-2025-07-24"
 MAX_POLL_WAIT = 7200  # 2 hours (ultra8x can take up to 2h)
 POLL_INTERVAL = 10
 
+# Local cache mapping run_id → fingerprint of the issuing key.
+# Used so --status / --result vend the same key that created the run.
+_RUN_OWNERS_FILE = CONFIG_DIR / "parallel-run-owners.json"
+
+# Max times we'll re-vend trying to land on the issuing fingerprint
+# before giving up and using whatever we got.
+_STICKY_VEND_ATTEMPTS = 6
+
 PROCESSORS = [
     "lite", "base", "core", "core2x", "pro", "ultra",
     "ultra2x", "ultra4x", "ultra8x",
@@ -42,6 +56,70 @@ PROCESSORS = [
 ]
 
 
+# ── Run-owner cache ──────────────────────────────────────────────
+
+def _load_run_owners() -> dict:
+    if _RUN_OWNERS_FILE.exists():
+        try:
+            return json.loads(_RUN_OWNERS_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def _remember_run_owner(run_id: str, fingerprint: str) -> None:
+    """Persist {run_id -> fingerprint} so later --status/--result can reuse the key."""
+    if not run_id or not fingerprint or fingerprint == "env":
+        return
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        owners = _load_run_owners()
+        owners[run_id] = fingerprint
+        # Cap entries (keep last 500) to bound file size
+        if len(owners) > 500:
+            owners = dict(list(owners.items())[-500:])
+        _RUN_OWNERS_FILE.write_text(json.dumps(owners))
+    except OSError:
+        pass
+
+
+def _recall_run_owner(run_id: str) -> str | None:
+    return _load_run_owners().get(run_id)
+
+
+def _get_key_for_run(run_id: str) -> str | None:
+    """
+    Vend a key suitable for operating on run_id.
+
+    If PARALLEL_API_KEY is set, use it (single-key mode).
+    Otherwise vend from gate. If we remember the issuing fingerprint for this
+    run, retry vending until it matches (gate is headroom-rotated, so we may
+    have to vend a few times). If we can't land on the right key, fall back
+    to whatever vended and warn — caller will see a 404 if it's the wrong org.
+    """
+    env_key = os.environ.get("PARALLEL_API_KEY")
+    if env_key:
+        return env_key
+
+    target = _recall_run_owner(run_id)
+    last_key = None
+    for _ in range(_STICKY_VEND_ATTEMPTS):
+        result = vend_key("parallel")
+        if not result:
+            return None
+        last_key = result["api_key"]
+        if target is None or result["fingerprint"] == target:
+            return last_key
+
+    if target is not None:
+        print(
+            f"  [warn] could not vend issuing key for {run_id} "
+            f"(wanted fingerprint {target[:8]}…); response may 404",
+            file=sys.stderr,
+        )
+    return last_key
+
+
 def _get_api_key() -> str:
     key = get_key_for_service("parallel", "PARALLEL_API_KEY")
     if not key:
@@ -87,7 +165,24 @@ def _api_request(method: str, path: str, api_key: str,
 
 # ── SSE streaming ────────────────────────────────────────────────
 
+def _sse_error_message(payload: dict) -> str:
+    """Pull a readable message out of a Parallel error payload."""
+    err = payload.get("error") if isinstance(payload, dict) else None
+    if isinstance(err, dict):
+        return err.get("message") or err.get("detail") or json.dumps(err)
+    return payload.get("message") or json.dumps(payload)
+
+
 def _stream_sse(api_key: str, run_id: str, quiet: bool = False) -> dict | None:
+    """
+    Stream task progress over SSE.
+
+    Returns:
+        dict   — task output (terminal state: completed)
+        None   — stream ended without terminal state; caller should poll
+    Exits:
+        2 — definitive error (task failed, run not found, wrong-org key)
+    """
     url = f"{API_BASE}/v1beta/tasks/runs/{run_id}/events"
     seen = set()
 
@@ -103,20 +198,45 @@ def _stream_sse(api_key: str, run_id: str, quiet: bool = False) -> dict | None:
 
         try:
             resp = urllib.request.urlopen(req, timeout=600)
+        except urllib.error.HTTPError as e:
+            try:
+                err_payload = json.loads(e.read().decode(errors="replace"))
+                msg = _sse_error_message(err_payload)
+            except Exception:
+                msg = str(e)
+            print(f"  ✗ SSE error ({e.code}): {msg}", file=sys.stderr)
+            sys.exit(2)
         except Exception as e:
             if not quiet:
-                print(f"  [sse] failed: {e}", file=sys.stderr)
+                print(f"  [sse] connect failed: {e}", file=sys.stderr)
             return None
 
+        # Detect non-SSE responses (HTTP 200 + JSON error body).
+        # Parallel returns this when the API key doesn't own the run_id, or
+        # when the run_id is malformed. The Content-Type is still
+        # `text/event-stream` so we can't rely on the header — instead we
+        # buffer non-SSE lines and, if we exit the loop without ever seeing
+        # a real SSE event, treat the buffer as a JSON error body.
+        saw_sse_event = False
+        non_sse_buffer: list[str] = []
+
         try:
             for raw_line in resp:
                 line = raw_line.decode("utf-8", errors="replace").rstrip("\n\r")
+                if not line:
+                    continue
                 if not line.startswith("data: "):
+                    # SSE comments start with ':' and field lines may be
+                    # `event:` / `id:` / `retry:` — ignore those, but capture
+                    # anything that looks like raw content for error-detect.
+                    if line[:1] not in (":",) and not line.startswith(("event:", "id:", "retry:")):
+                        non_sse_buffer.append(line)
                     continue
                 try:
                     event = json.loads(line[6:])
                 except json.JSONDecodeError:
                     continue
+                saw_sse_event = True
 
                 etype = event.get("type", "")
 
@@ -144,12 +264,27 @@ def _stream_sse(api_key: str, run_id: str, quiet: bool = False) -> dict | None:
                         sys.exit(2)
 
                 elif etype == "error":
-                    return None
+                    msg = _sse_error_message(event)
+                    print(f"  ✗ SSE error event: {msg}", file=sys.stderr)
+                    sys.exit(2)
         except Exception:
             pass
         finally:
             resp.close()
 
+        # If the stream produced zero SSE events but had body content,
+        # it's almost certainly an error response (wrong-org key, bad run_id).
+        # Surface it and bail rather than silently reconnecting 25 times.
+        if not saw_sse_event and non_sse_buffer:
+            body = "\n".join(non_sse_buffer)
+            try:
+                payload = json.loads(body)
+                msg = _sse_error_message(payload)
+            except json.JSONDecodeError:
+                msg = body[:300]
+            print(f"  ✗ SSE refused: {msg}", file=sys.stderr)
+            sys.exit(2)
+
     return None
 
 
@@ -345,10 +480,15 @@ def cmd_run(args):
     if getattr(args, "follow_up", None):
         body["previous_interaction_id"] = args.follow_up
 
-    # Submit with retry — vend key, submit task, retry on 402/429
+    # Submit with retry — vend key, submit task, retry on 402/429.
+    # Capture the issuing VendedKey so SSE + polling use the SAME key.
+    # Without this, gate may vend a different org's key for the followup
+    # GET/SSE calls, causing the streamed run_id to look "not found".
     headers = {"parallel-beta": SSE_BETA}
+    captured: dict = {"key": None}
 
     def submit(key):
+        captured["key"] = key
         return _api_request("POST", "/v1/tasks/runs", key.api_key,
                             body=body, extra_headers=headers, raise_on_error=True)
 
@@ -385,11 +525,17 @@ def cmd_run(args):
             print("  ✗ no Parallel API key. Set PARALLEL_API_KEY or add one via the dashboard.", file=sys.stderr)
         return 1
 
-    # From here on, use the same key for polling (already authenticated)
-    api_key = _get_api_key()
+    # Reuse the SAME key that submitted the task for SSE + polling.
+    vended = captured["key"]
+    api_key = vended.api_key if vended is not None else _get_api_key()
     run_id = task["run_id"]
     created_at = task.get("created_at", "")
 
+    # Remember which gate-vended key owns this run, so later
+    # `escli research --status/--result <run_id>` can vend the same one.
+    if vended is not None:
+        _remember_run_owner(run_id, vended.fingerprint)
+
     if not args.quiet:
         print(f"  · run_id: {run_id}", file=sys.stderr)
 
@@ -436,7 +582,7 @@ def cmd_run(args):
 
 def cmd_status(args):
     """Check task run status."""
-    api_key = _get_api_key()
+    api_key = _get_key_for_run(args.run_id) or _get_api_key()
     result = _api_request("GET", f"/v1/tasks/runs/{args.run_id}", api_key)
 
     if args.json:
@@ -511,7 +657,7 @@ def cmd_processors(args):
 
 def cmd_result(args):
     """Fetch completed task result."""
-    api_key = _get_api_key()
+    api_key = _get_key_for_run(args.run_id) or _get_api_key()
 
     # Check status first
     run = _api_request("GET", f"/v1/tasks/runs/{args.run_id}", api_key)
@@ -554,7 +700,7 @@ def register(subparsers):
     F = argparse.RawDescriptionHelpFormatter
 
     p = subparsers.add_parser(
-        "research", aliases=["r"], help="Web research tasks (Parallel Task API)",
+        "research", aliases=["r"], help="Run deep web research tasks",
         formatter_class=F,
         epilog="""modes:
   escli research "query" -o report.md          Run a research task (default)
@@ -591,31 +737,31 @@ output modes:
     mode_g.add_argument("--result", default=None, metavar="RUN_ID", help="Fetch completed task result")
 
     # Run options
-    p.add_argument("-o", "--output", default=None, help="Output file path (markdown or JSON)")
+    p.add_argument("-o", "--output", default=None, help="Output path (md or json)")
     p.add_argument("-p", "--processor", default="pro", choices=PROCESSORS, help="Processor tier (default: pro)")
 
     # Output schema
     schema_g = p.add_argument_group("output schema")
-    schema_g.add_argument("--text", action="store_true", help="Markdown report format")
+    schema_g.add_argument("--text", action="store_true", help="Markdown report output")
     schema_g.add_argument("--schema", default=None, metavar="FILE", help="JSON Schema file for structured output")
-    schema_g.add_argument("--output-schema", default=None, metavar="STR", help="Inline output schema description")
+    schema_g.add_argument("--output-schema", default=None, metavar="STR", help="Inline schema description")
 
     # Input
     input_g = p.add_argument_group("input")
-    input_g.add_argument("--input-json", default=None, metavar="JSON", help="JSON object as input (instead of text)")
-    input_g.add_argument("--input-file", default=None, metavar="FILE", help="JSON file as input")
+    input_g.add_argument("--input-json", default=None, metavar="JSON", help="JSON input (instead of text)")
+    input_g.add_argument("--input-file", default=None, metavar="FILE", help="JSON input file")
 
     # Source policy
     source_g = p.add_argument_group("source policy")
     source_g.add_argument("--include-domains", default=None, metavar="D1,D2", help="Only use these domains")
     source_g.add_argument("--exclude-domains", default=None, metavar="D1,D2", help="Exclude these domains")
-    source_g.add_argument("--after-date", default=None, metavar="YYYY-MM-DD", help="Only content after this date")
+    source_g.add_argument("--after-date", default=None, metavar="YYYY-MM-DD", help="Filter content after this date")
 
     # Advanced
     adv_g = p.add_argument_group("advanced")
-    adv_g.add_argument("--location", default=None, metavar="CC", help="ISO country code for geo-targeted results")
+    adv_g.add_argument("--location", default=None, metavar="CC", help="ISO country code for geo-targeting")
     adv_g.add_argument("--metadata", default=None, help="Metadata as JSON or key=val,key=val")
-    adv_g.add_argument("--follow-up", default=None, metavar="RUN_ID", help="Follow-up on a previous task run")
+    adv_g.add_argument("--follow-up", default=None, metavar="RUN_ID", help="Follow up on a previous run")
     adv_g.add_argument("--no-basis", action="store_true", help="Exclude citations and reasoning")
 
     p.set_defaults(func=_dispatch)

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/search.py

@@ -268,7 +268,7 @@ def register(subparsers):
 
     # search
     search_p = subparsers.add_parser(
-        "search", aliases=["s"], help="Web search (Parallel.ai)",
+        "search", aliases=["s"], help="Search the web, return ranked excerpts",
         formatter_class=F,
         epilog="""examples:
   escli search "latest cloudflare workers features"
@@ -278,14 +278,14 @@ def register(subparsers):
 Uses the free Parallel Search MCP. No API key needed.
 Add a Parallel API key for higher rate limits.
 """)
-    search_p.add_argument("objective", nargs="+", help="What you're searching for")
+    search_p.add_argument("objective", nargs="+", help="Search objective")
     search_p.add_argument("--queries", nargs="+", default=None, metavar="Q",
-                          help="Specific search queries (default: uses objective)")
+                          help="Override queries (default: objective)")
     search_p.set_defaults(func=cmd_search)
 
     # fetch
     fetch_p = subparsers.add_parser(
-        "fetch", aliases=["f"], help="Extract URL content (Parallel.ai)",
+        "fetch", aliases=["f"], help="Extract clean content from URLs",
         formatter_class=F,
         epilog="""examples:
   escli fetch https://docs.parallel.ai/search/search-quickstart
@@ -295,9 +295,9 @@ Add a Parallel API key for higher rate limits.
 
 Uses the free Parallel Extract MCP. No API key needed.
 """)
-    fetch_p.add_argument("urls", nargs="+", help="URLs to extract content from")
-    fetch_p.add_argument("--objective", default=None, help="Focus extraction on this topic")
-    fetch_p.add_argument("--full", action="store_true", help="Return full page content instead of excerpts")
+    fetch_p.add_argument("urls", nargs="+", help="URLs to extract")
+    fetch_p.add_argument("--objective", default=None, help="Focus on this topic")
+    fetch_p.add_argument("--full", action="store_true", help="Return full content (not excerpts)")
     fetch_p.set_defaults(func=cmd_fetch)
 
     return search_p

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/social.py

@@ -215,7 +215,7 @@ def register(subparsers):
     F = argparse.RawDescriptionHelpFormatter
 
     p = subparsers.add_parser(
-        "social", help="Social media search (Tavily)",
+        "social", help="Search posts across social platforms",
         formatter_class=F,
         epilog="""platforms:
   reddit, x, tiktok, linkedin, instagram, facebook, youtube, combined (default)
@@ -235,11 +235,11 @@ time ranges:
   year    Last 12 months
 """)
 
-    p.add_argument("query", nargs="+", help="What to search for on social media")
+    p.add_argument("query", nargs="+", help="Search query")
     p.add_argument("--platform", "-p", default=None, metavar="P",
-                   help=f"Platform(s) to search, comma-separated ({', '.join(VALID_PLATFORMS)})")
+                   help=f"Platform(s), comma-separated ({', '.join(VALID_PLATFORMS)})")
     p.add_argument("--time", "-t", default=None, choices=VALID_TIME_RANGES, metavar="T",
-                   help="Time range: day, week, month, year")
+                   help="Time range: day|week|month|year")
     p.add_argument("--max-results", "-n", type=int, default=10, metavar="N",
                    help="Max results (1-20, default: 10)")
     p.add_argument("--depth", default="advanced", choices=VALID_DEPTHS,
@@ -247,11 +247,11 @@ time ranges:
     p.add_argument("--answer", "-a", action="store_true",
                    help="Include AI-synthesized answer")
     p.add_argument("--raw", action="store_true",
-                   help="Include full post content (raw markdown)")
+                   help="Include full post content")
     p.add_argument("--images", action="store_true",
-                   help="Include images from results")
+                   help="Include images")
     p.add_argument("--country", default=None, metavar="CC",
-                   help="Country for geo-targeted results (e.g. 'united states')")
+                   help="Country for geo-targeting (e.g. 'united states')")
     p.set_defaults(func=cmd_social)
 
     return p

{eightstatecli-0.4.1 → eightstatecli-0.4.3}/src/escli/commands/usage.py

@@ -390,7 +390,7 @@ def register(subparsers):
     F = argparse.RawDescriptionHelpFormatter
 
     p = subparsers.add_parser(
-        "usage", aliases=["u"], help="API usage and spend analytics",
+        "usage", aliases=["u"], help="Show API usage and spend",
         formatter_class=F,
         epilog=f"""examples:
   escli usage                          {DOT} summary, last 30 days
@@ -418,11 +418,11 @@ auth: requires `escli auth login` (uses CLI token, not API key).
     p.add_argument("--days", type=int, default=30, metavar="N",
                    help="Window size in days (default: 30)")
     p.add_argument("--service", default=None, metavar="NAME",
-                   help="Filter to a single service (e.g. parallel, openai, assemblyai)")
+                   help="Filter to one service (parallel|openai|assemblyai|...)")
     p.add_argument("--daily", action="store_true",
-                   help="Show day-by-day breakdown")
+                   help="Day-by-day breakdown")
     p.add_argument("--pricing", action="store_true",
-                   help="Show current pricing rules (ignores --days/--service)")
+                   help="Show current pricing rules")
     p.set_defaults(func=cmd_usage)
 
     return p