eightstatecli 0.4.0__py3-none-any.whl

escli/__init__.py

@@ -0,0 +1,837 @@
+#!/usr/bin/env python3
+"""
+escli — Eightstate CLI
+
+A unified CLI for Eightstate AI services. Designed for both human operators
+and AI agents (Claude Code, Codex, etc.).
+
+AGENT INSTRUCTIONS:
+  - Use --json for all commands to get structured JSON output to stdout
+  - Use --quiet to suppress stderr progress messages
+  - Auth: set ESCLI_API_KEY env var OR run: escli auth login --key <key>
+  - Generate: escli --json --quiet image gen "prompt" -s <size> -o output.png
+  - Edit:     escli --json --quiet image edit "instruction" -i input.png -o output.png
+  - Docs:     escli --json --quiet docs get react "useEffect cleanup"
+  - Audio:    escli --json --quiet audio transcribe file.mp3 --speakers
+  - JSON output schema: {"success": bool, ...}
+  - Exit codes: 0=success, 1=error, 2=usage
+"""
+
+__version__ = "0.4.0"
+
+import argparse
+import base64
+import json as jsonlib
+import os
+import pathlib
+import sys
+import time
+from datetime import datetime
+
+# ─────────────────────────────────────────────────────────────────────
+# Branding
+# ─────────────────────────────────────────────────────────────────────
+BANNER_COMPACT = r"""
+  ┌─────────────────────────────────┐
+  │  escli                   v""" + __version__ + r"""  │
+  │  eightstate command line        │
+  └─────────────────────────────────┘"""
+
+# Box drawing
+BOX_H = "─"; BOX_V = "│"; BOX_TL = "┌"; BOX_TR = "┐"; BOX_BL = "└"; BOX_BR = "┘"
+BOX_T = "├"; BOX_B = "┤"
+DOT = "·"; BULLET = "▸"; CHECK = "✓"; CROSS = "✗"; ARROW = "→"
+BLOCK = "█"; SHADE = "░"; PIPE = "│"
+
+
+def box(title: str, lines: list[str], width: int = 45) -> str:
+    inner = width - 4
+    out = [f"  {BOX_TL}{BOX_H * (width - 2)}{BOX_TR}",
+           f"  {BOX_V}  {title:<{inner}}{BOX_V}",
+           f"  {BOX_T}{BOX_H * (width - 2)}{BOX_B}"]
+    for line in lines:
+        out.append(f"  {BOX_V}  {line[:inner]:<{inner}}{BOX_V}")
+    out.append(f"  {BOX_BL}{BOX_H * (width - 2)}{BOX_BR}")
+    return "\n".join(out)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Paths & Defaults
+# ─────────────────────────────────────────────────────────────────────
+CONFIG_DIR  = pathlib.Path(os.environ.get("ESCLI_CONFIG_DIR", pathlib.Path.home() / ".escli"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+ENDPOINT    = "https://ai.eightstate.co/v1"
+
+GATE_URL = os.environ.get("ESCLI_GATE_URL", "https://internal.eightstate.co")
+
+DEFAULTS = {
+    "model": "gpt-image-2", "quality": "high", "size": "1024x1024",
+    "format": "png", "out_dir": ".", "timeout": 300,
+}
+
+SIZE_ALIASES = {
+    "square": "1024x1024", "sq": "1024x1024",
+    "landscape": "1536x1024", "land": "1536x1024", "ls": "1536x1024", "wide": "1536x1024",
+    "portrait": "1024x1536", "port": "1024x1536", "tall": "1024x1536",
+    "1024x1024": "1024x1024", "1536x1024": "1536x1024", "1024x1536": "1024x1536",
+}
+
+VALID_QUALITIES   = ["low", "medium", "high"]
+VALID_FORMATS     = ["png", "jpeg", "jpg", "webp"]
+VALID_BACKGROUNDS = ["auto", "transparent"]
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Config store
+# ─────────────────────────────────────────────────────────────────────
+def _load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return jsonlib.loads(CONFIG_FILE.read_text())
+        except (jsonlib.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def _save_config(cfg: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(jsonlib.dumps(cfg, indent=2) + "\n")
+    CONFIG_FILE.chmod(0o600)
+
+
+def get_active_profile_name() -> str:
+    return _load_config().get("active_profile", "default")
+
+
+def get_profile(name: str = None) -> dict:
+    cfg = _load_config()
+    if name is None:
+        name = cfg.get("active_profile", "default")
+    profile = cfg.get("profiles", {}).get(name, {})
+    return {
+        "name": name,
+        "api_key": profile.get("api_key") or os.environ.get("ESCLI_API_KEY", ""),
+        "endpoint": profile.get("endpoint") or os.environ.get("ESCLI_BASE_URL", ENDPOINT),
+        "label": profile.get("label", name),
+    }
+
+
+def set_profile(name, api_key, label=None, endpoint=None):
+    cfg = _load_config()
+    cfg.setdefault("profiles", {})[name] = {
+        "api_key": api_key, "endpoint": endpoint or ENDPOINT,
+        "label": label or name, "created": datetime.now().isoformat(),
+    }
+    cfg["active_profile"] = name
+    _save_config(cfg)
+
+
+def delete_profile(name):
+    cfg = _load_config()
+    profiles = cfg.get("profiles", {})
+    if name not in profiles:
+        return False
+    del profiles[name]
+    if cfg.get("active_profile") == name:
+        remaining = list(profiles.keys())
+        cfg["active_profile"] = remaining[0] if remaining else ""
+    _save_config(cfg)
+    return True
+
+
+def list_profiles():
+    cfg = _load_config()
+    active = cfg.get("active_profile", "default")
+    return [{
+        "name": n, "label": d.get("label", n),
+        "key": f"{d.get('api_key','')[:8]}...{d.get('api_key','')[-4:]}" if len(d.get("api_key","")) > 12 else "***",
+        "endpoint": d.get("endpoint", ENDPOINT),
+        "active": n == active, "created": d.get("created", ""),
+    } for n, d in cfg.get("profiles", {}).items()]
+
+
+def resolve_api_key(args):
+    if getattr(args, "_explicit_api_key", None):
+        return args._explicit_api_key
+    p = get_profile()
+    return p["api_key"] or os.environ.get("ESCLI_API_KEY", "")
+
+
+def resolve_endpoint(args):
+    if getattr(args, "_explicit_base_url", None):
+        return args._explicit_base_url
+    return get_profile().get("endpoint", ENDPOINT)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────
+def slugify(text, max_len=40):
+    slug = "".join(c if c.isalnum() or c == " " else "" for c in text.lower().strip())
+    return "-".join(slug.split())[:max_len] or "image"
+
+def auto_filename(prompt, ext="png"):
+    return f"{datetime.now().strftime('%Y%m%d-%H%M%S')}-{slugify(prompt)}.{ext}"
+
+def log(msg, quiet=False):
+    if not quiet:
+        print(msg, file=sys.stderr)
+
+def resolve_size(value):
+    key = value.lower().strip()
+    if key in SIZE_ALIASES:
+        return SIZE_ALIASES[key]
+    print(f"  {CROSS} invalid size: {value}", file=sys.stderr)
+    sys.exit(2)
+
+def mask_key(key):
+    return f"{key[:8]}...{key[-4:]}" if len(key) > 12 else "***"
+
+def require_openai():
+    try:
+        from openai import OpenAI
+        return OpenAI
+    except ImportError:
+        print(f"  {CROSS} missing: openai SDK. pip install openai", file=sys.stderr)
+        sys.exit(1)
+
+def require_httpx():
+    try:
+        import httpx
+        return httpx
+    except ImportError:
+        print(f"  {CROSS} missing: httpx. pip install httpx", file=sys.stderr)
+        sys.exit(1)
+
+def open_file(path):
+    import subprocess
+    if sys.platform == "darwin":
+        subprocess.run(["open", str(path)], check=False)
+    elif sys.platform == "linux":
+        subprocess.run(["xdg-open", str(path)], check=False)
+    elif sys.platform == "win32":
+        os.startfile(str(path))
+
+def ensure_authed(args):
+    api_key, base_url = resolve_api_key(args), resolve_endpoint(args)
+    if not api_key:
+        log(f"\n  {CROSS} not authenticated\n  {ARROW} run: escli auth login\n", getattr(args, 'quiet', False))
+        sys.exit(1)
+    return api_key, base_url
+
+def validate_key(api_key, endpoint, timeout=15):
+    OpenAI = require_openai()
+    try:
+        client = OpenAI(base_url=endpoint, api_key=api_key, timeout=timeout)
+        return True, f"{len(client.models.list().data)} models"
+    except Exception as e:
+        err = str(e)
+        if "401" in err or "Unauthorized" in err:
+            return False, "invalid key"
+        if "403" in err or "Forbidden" in err:
+            return False, "not authorized"
+        return False, f"connection error: {err[:80]}"
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Commands
+# ─────────────────────────────────────────────────────────────────────
+
+def cmd_auth_login(args):
+    # Legacy: --key flag for direct API key login (image proxy)
+    if getattr(args, "key", None):
+        return _legacy_key_login(args)
+
+    # Device flow via gate + Clerk
+    log("", args.quiet)
+    log(BANNER_COMPACT, args.quiet)
+    log("", args.quiet)
+    log(f"  {BULLET} logging in via eightstate...", args.quiet)
+
+    httpx = require_httpx()
+    try:
+        resp = httpx.post(f"{GATE_URL}/api/auth/device", timeout=10)
+        resp.raise_for_status()
+        data = resp.json()
+    except Exception as e:
+        if args.json: print(jsonlib.dumps({"success": False, "error": f"failed to reach gate: {e}"}))
+        else: log(f"  {CROSS} failed to reach {GATE_URL}: {e}", args.quiet)
+        return 1
+
+    device_code = data["device_code"]
+    user_code = data["user_code"]
+    verification_url = data["verification_url"]
+    interval = data.get("interval", 5)
+
+    log(f"  {DOT} opening browser...", args.quiet)
+    log(f"  {DOT} confirm code: {user_code}", args.quiet)
+    log("", args.quiet)
+
+    # Open browser
+    import subprocess, webbrowser
+    try:
+        webbrowser.open(verification_url)
+    except Exception:
+        log(f"  {ARROW} open this URL: {verification_url}", args.quiet)
+
+    log(f"  {SHADE * 30}  waiting for auth...", args.quiet)
+
+    # Poll
+    import time as _time
+    deadline = _time.time() + 900  # 15 min max
+    while _time.time() < deadline:
+        _time.sleep(interval)
+        try:
+            poll_resp = httpx.post(
+                f"{GATE_URL}/api/auth/poll",
+                json={"device_code": device_code},
+                timeout=10,
+            )
+            poll_data = poll_resp.json()
+        except Exception:
+            continue
+
+        if poll_data.get("status") == "authorized":
+            cli_token = poll_data["token"]
+            # Store the CLI token
+            profile_name = getattr(args, "profile", None) or "default"
+            cfg = _load_config()
+            cfg.setdefault("profiles", {})[profile_name] = {
+                "cli_token": cli_token,
+                "endpoint": GATE_URL,
+                "label": getattr(args, "label", None) or profile_name,
+                "created": datetime.now().isoformat(),
+            }
+            cfg["active_profile"] = profile_name
+            _save_config(cfg)
+
+            if args.json:
+                print(jsonlib.dumps({"success": True, "profile": profile_name, "gate": GATE_URL}))
+            else:
+                log("", args.quiet)
+                log(box(f"{CHECK} authenticated", [
+                    f"profile   {profile_name}",
+                    f"gate      {GATE_URL}",
+                    f"config    {CONFIG_FILE}",
+                ]), args.quiet)
+                log("", args.quiet)
+            return 0
+
+        if poll_data.get("status") == "expired":
+            if args.json: print(jsonlib.dumps({"success": False, "error": "session expired"}))
+            else: log(f"  {CROSS} session expired. try again.", args.quiet)
+            return 1
+
+    if args.json: print(jsonlib.dumps({"success": False, "error": "timed out"}))
+    else: log(f"  {CROSS} timed out waiting for auth.", args.quiet)
+    return 1
+
+
+def _legacy_key_login(args):
+    """Legacy login with a direct API key (for image proxy)."""
+    endpoint = getattr(args, "endpoint", None) or ENDPOINT
+    api_key = args.key
+    profile_name = getattr(args, "profile", None) or "default"
+    label = getattr(args, "label", None) or profile_name
+
+    log(f"  {DOT} validating against {endpoint}...", args.quiet)
+    ok, msg = validate_key(api_key, endpoint)
+    if not ok:
+        if args.json: print(jsonlib.dumps({"success": False, "error": msg}))
+        else: log(f"  {CROSS} {msg}", args.quiet)
+        return 1
+
+    set_profile(profile_name, api_key, label=label, endpoint=endpoint)
+    masked = mask_key(api_key)
+    if args.json:
+        print(jsonlib.dumps({"success": True, "profile": profile_name, "key": masked,
+                             "endpoint": endpoint, "models": msg, "config_path": str(CONFIG_FILE)}))
+    else:
+        log("", args.quiet)
+        log(box(f"{CHECK} authenticated", [f"profile   {profile_name}", f"key       {masked}",
+                                           f"models    {msg}", f"config    {CONFIG_FILE}"]), args.quiet)
+        log("", args.quiet)
+    return 0
+
+
+def cmd_auth_logout(args):
+    profile_name = getattr(args, "profile", None) or get_active_profile_name()
+    if getattr(args, "all", False):
+        if CONFIG_FILE.exists(): CONFIG_FILE.unlink()
+        if args.json: print(jsonlib.dumps({"success": True, "message": "all profiles removed"}))
+        else: log(f"  {CHECK} all profiles removed", args.quiet)
+        return 0
+    deleted = delete_profile(profile_name)
+    if args.json: print(jsonlib.dumps({"success": True, "profile": profile_name, "deleted": deleted}))
+    else: log(f"  {CHECK if deleted else CROSS} profile '{profile_name}' {'removed' if deleted else 'not found'}", args.quiet)
+    return 0
+
+
+def cmd_auth_status(args):
+    profile = get_profile()
+    has_key = bool(profile["api_key"])
+    if args.json:
+        r = {"authenticated": has_key, "profile": profile["name"], "endpoint": profile["endpoint"],
+             "config_path": str(CONFIG_FILE)}
+        if has_key: r["key"] = mask_key(profile["api_key"])
+        print(jsonlib.dumps(r))
+    else:
+        if has_key:
+            print(box(f"{CHECK} authenticated", [f"profile   {profile['name']}",
+                                                  f"key       {mask_key(profile['api_key'])}",
+                                                  f"endpoint  {profile['endpoint']}"]))
+        else: print(f"\n  {CROSS} not authenticated\n  {ARROW} run: escli auth login\n")
+    return 0
+
+
+def cmd_auth_profiles(args):
+    profiles = list_profiles()
+    if args.json:
+        print(jsonlib.dumps({"success": True, "profiles": profiles, "count": len(profiles)})); return 0
+    if not profiles: print(f"  {CROSS} no profiles. run: escli auth login"); return 0
+    print(f"\n  {'':2}{'PROFILE':<16} {'KEY':<24} {'ENDPOINT'}")
+    print(f"  {BOX_H * 65}")
+    for p in profiles:
+        print(f"  {BULLET if p['active'] else ' '} {p['name']:<15} {p['key']:<24} {p['endpoint']}")
+    print(f"\n  {len(profiles)} profile(s) {DOT} active: {get_active_profile_name()}\n")
+    return 0
+
+
+def cmd_auth_switch(args):
+    target = args.profile_name
+    cfg = _load_config()
+    profiles = cfg.get("profiles", {})
+    if target not in profiles:
+        if args.json: print(jsonlib.dumps({"success": False, "error": f"profile '{target}' not found"}))
+        else: log(f"  {CROSS} profile '{target}' not found", args.quiet)
+        return 1
+    cfg["active_profile"] = target; _save_config(cfg)
+    if args.json: print(jsonlib.dumps({"success": True, "active_profile": target}))
+    else: log(f"  {CHECK} switched {ARROW} {target}", args.quiet)
+    return 0
+
+
+def cmd_image_generate(args):
+    api_key, base_url = ensure_authed(args)
+    OpenAI = require_openai()
+    client = OpenAI(base_url=base_url, api_key=api_key, timeout=args.timeout)
+    prompt = " ".join(args.prompt)
+    if not prompt: print(f"  {CROSS} prompt required", file=sys.stderr); sys.exit(1)
+
+    size = resolve_size(args.size)
+    ext = args.format if args.format != "jpg" else "jpeg"
+    out_ext = args.format if args.format != "jpeg" else "jpg"
+    out_path = pathlib.Path(args.output) if args.output else pathlib.Path(args.out_dir) / auto_filename(prompt, out_ext)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    log("", args.quiet)
+    log(f"  {BULLET} prompt    {prompt}", args.quiet)
+    log(f"  {DOT} size      {size}  {DOT} quality   {args.quality}  {DOT} format   {args.format}", args.quiet)
+    log(f"  {DOT} model     {args.model}", args.quiet)
+    log(f"  {DOT} output    {out_path}", args.quiet)
+    log("", args.quiet)
+    log(f"  {SHADE * 30}  generating...", args.quiet)
+
+    extra_body = {}
+    if args.format and args.format != "png": extra_body["output_format"] = ext
+    if args.background: extra_body["background"] = args.background
+    if args.compression is not None: extra_body["output_compression"] = args.compression
+    if args.moderation: extra_body["moderation"] = args.moderation
+
+    t0 = time.time()
+    try:
+        kwargs = dict(model=args.model, prompt=prompt, size=size, quality=args.quality, response_format="b64_json")
+        if extra_body: kwargs["extra_body"] = extra_body
+        resp = client.images.generate(**kwargs)
+    except Exception as e:
+        if args.json: print(jsonlib.dumps({"error": str(e), "success": False}))
+        else: log(f"  {CROSS} {e}", args.quiet)
+        sys.exit(1)
+
+    elapsed = round(time.time() - t0, 1)
+    raw = base64.b64decode(resp.data[0].b64_json)
+    out_path.write_bytes(raw)
+    revised = getattr(resp.data[0], "revised_prompt", None)
+    kb = len(raw) / 1024
+
+    if args.json:
+        result = {"success": True, "path": str(out_path.resolve()), "size_bytes": len(raw),
+                  "elapsed_seconds": elapsed, "prompt": prompt, "model": args.model,
+                  "image_size": size, "quality": args.quality}
+        if revised: result["revised_prompt"] = revised
+        print(jsonlib.dumps(result))
+    else:
+        log(f"  {BLOCK * 30}  done", args.quiet)
+        log("", args.quiet)
+        log(f"  {CHECK} {out_path}", args.quiet)
+        log(f"    {elapsed}s {DOT} {kb:.0f}kb {DOT} {size}", args.quiet)
+        if revised: log(f"    revised: {revised[:80]}...", args.quiet)
+        log("", args.quiet)
+        if args.quiet: print(str(out_path.resolve()))
+
+    if args.open: open_file(out_path)
+    return 0
+
+
+def cmd_image_edit(args):
+    api_key, base_url = ensure_authed(args)
+    httpx = require_httpx()
+    prompt = " ".join(args.prompt)
+    if not prompt: print(f"  {CROSS} prompt required", file=sys.stderr); sys.exit(1)
+
+    input_path = pathlib.Path(args.input)
+    if not input_path.exists(): print(f"  {CROSS} not found: {input_path}", file=sys.stderr); sys.exit(1)
+
+    size = resolve_size(args.size)
+    img_b64 = base64.b64encode(input_path.read_bytes()).decode()
+    mime = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+            ".webp": "image/webp"}.get(input_path.suffix.lower(), "image/png")
+    out_ext = args.format if args.format != "jpeg" else "jpg"
+    out_path = pathlib.Path(args.output) if args.output else pathlib.Path(args.out_dir) / auto_filename(prompt, out_ext)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    log("", args.quiet)
+    log(f"  {BULLET} input     {input_path}", args.quiet)
+    log(f"  {BULLET} prompt    {prompt}", args.quiet)
+    log(f"  {DOT} size      {size}  {DOT} quality   {args.quality}", args.quiet)
+    log(f"  {DOT} output    {out_path}", args.quiet)
+    log("", args.quiet)
+    log(f"  {SHADE * 30}  editing...", args.quiet)
+
+    body = {"model": args.model, "prompt": prompt,
+            "images": [{"image_url": f"data:{mime};base64,{img_b64}"}],
+            "size": size, "quality": args.quality, "response_format": "b64_json"}
+    ext = args.format if args.format != "jpg" else "jpeg"
+    if args.format and args.format != "png": body["output_format"] = ext
+    if args.compression is not None: body["output_compression"] = args.compression
+    if args.fidelity: body["input_fidelity"] = args.fidelity
+
+    t0 = time.time()
+    try:
+        r = httpx.post(f"{base_url}/images/edits",
+                       headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+                       json=body, timeout=args.timeout)
+        r.raise_for_status(); data = r.json()
+    except Exception as e:
+        if args.json: print(jsonlib.dumps({"error": str(e), "success": False}))
+        else: log(f"  {CROSS} {e}", args.quiet)
+        sys.exit(1)
+
+    elapsed = round(time.time() - t0, 1)
+    raw = base64.b64decode(data["data"][0]["b64_json"])
+    out_path.write_bytes(raw); kb = len(raw) / 1024
+
+    if args.json:
+        print(jsonlib.dumps({"success": True, "path": str(out_path.resolve()), "size_bytes": len(raw),
+                             "elapsed_seconds": elapsed, "prompt": prompt, "input": str(input_path.resolve()),
+                             "model": args.model, "image_size": size, "quality": args.quality}))
+    else:
+        log(f"  {BLOCK * 30}  done", args.quiet); log("", args.quiet)
+        log(f"  {CHECK} {out_path}", args.quiet)
+        log(f"    {elapsed}s {DOT} {kb:.0f}kb {DOT} {size}", args.quiet); log("", args.quiet)
+        if args.quiet: print(str(out_path.resolve()))
+
+    if args.open: open_file(out_path)
+    return 0
+
+
+def cmd_models(args):
+    api_key, base_url = ensure_authed(args)
+    OpenAI = require_openai()
+    try:
+        models = OpenAI(base_url=base_url, api_key=api_key, timeout=30).models.list()
+    except Exception as e:
+        if args.json: print(jsonlib.dumps({"error": str(e), "success": False}))
+        else: print(f"  {CROSS} {e}", file=sys.stderr)
+        sys.exit(1)
+    model_list = sorted([m.id for m in models.data])
+    if args.json:
+        print(jsonlib.dumps({"success": True, "models": model_list, "count": len(model_list)}))
+    else:
+        print(f"\n  {'MODEL':<40}"); print(f"  {BOX_H * 40}")
+        for m in model_list: print(f"  {m}")
+        print(f"\n  {len(model_list)} models available\n")
+    return 0
+
+
+def cmd_version(args):
+    if args.json: print(jsonlib.dumps({"version": __version__, "endpoint": ENDPOINT}))
+    else: print(BANNER_COMPACT)
+    return 0
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Parser — with full agent-readable help on every subcommand
+# ─────────────────────────────────────────────────────────────────────
+def build_parser():
+    F = argparse.RawDescriptionHelpFormatter
+
+    root = argparse.ArgumentParser(prog="escli", description=BANNER_COMPACT + "\n", formatter_class=F, epilog=f"""quickstart:
+  escli auth login                            {DOT} authenticate
+  escli image gen "a sunset over the ocean"   {DOT} generate
+  escli models                                {DOT} list models
+
+examples:
+  escli i g "landscape" -s wide -q high --open
+  escli i e "repaint as watercolor" -i photo.jpg --open
+  escli --json --quiet i g "a logo"           {DOT} agent mode
+
+shortcuts:
+  i g  {ARROW} image generate    a    {ARROW} auth
+  i e  {ARROW} image edit        m    {ARROW} models
+
+sizes:
+  square {PIPE} sq       1024x1024   (default)
+  landscape {PIPE} wide  1536x1024
+  portrait {PIPE} tall   1024x1536
+
+agent usage:
+  {DOT} always pass --json for structured output to stdout
+  {DOT} pass --quiet to suppress stderr progress messages
+  {DOT} set ESCLI_API_KEY env var to skip auth login
+  {DOT} output JSON schema:
+    {{"success": true, "path": "/abs/path.png", "size_bytes": 123456,
+     "elapsed_seconds": 18.4, "prompt": "...", "model": "gpt-image-2",
+     "image_size": "1024x1024", "quality": "high"}}
+  {DOT} on error: {{"success": false, "error": "message"}}
+  {DOT} exit codes: 0=success, 1=error, 2=usage
+
+env vars:
+  ESCLI_API_KEY         API key (overrides stored profile)
+  ESCLI_BASE_URL        API endpoint (default: {ENDPOINT})
+  ESCLI_IMAGE_MODEL     Default model (default: gpt-image-2)
+  ESCLI_IMAGE_QUALITY   Default quality: low | medium | high (default: high)
+  ESCLI_IMAGE_SIZE      Default size (default: 1024x1024)
+  ESCLI_IMAGE_FORMAT    Default format: png | jpeg | webp (default: png)
+  ESCLI_OUT_DIR         Output directory (default: .)
+  ESCLI_TIMEOUT         Timeout in seconds (default: 300)
+  ESCLI_CONFIG_DIR      Config directory (default: ~/.escli)
+
+config: ~/.escli/config.json (600 permissions, owner-only)
+""")
+    root.add_argument("-v", "--version", action="store_true", help="Show version")
+    root.add_argument("--json", action="store_true", default=False, help="Structured JSON output (agent-friendly)")
+    root.add_argument("--quiet", action="store_true", default=False, help="Suppress stderr progress, print only result to stdout")
+    root.add_argument("--describe", action="store_true", default=False, help="Machine-readable JSON manifest of all commands (for agent discovery)")
+    root.add_argument("--base-url", dest="_explicit_base_url", default=None, help=argparse.SUPPRESS)
+    root.add_argument("--api-key", dest="_explicit_api_key", default=None, help=argparse.SUPPRESS)
+    root.add_argument("--timeout", type=int, default=int(os.environ.get("ESCLI_TIMEOUT", "300")), help=argparse.SUPPRESS)
+
+    subs = root.add_subparsers(dest="command", metavar="command")
+
+    # ── auth ──────────────────────────────────────────────────────────
+    auth_p = subs.add_parser("auth", aliases=["a"], help="Authentication and profiles", formatter_class=F,
+                             epilog=f"""subcommands:
+  login    {DOT} authenticate with API key
+  logout   {DOT} remove credentials
+  status   {DOT} show current profile (alias: whoami)
+  profiles {DOT} list all profiles (alias: ls)
+  switch   {DOT} switch active profile (alias: use)
+
+agent examples:
+  escli auth login --key sk-xxx              {DOT} non-interactive login
+  escli --json auth status                   {DOT} check if authenticated
+  ESCLI_API_KEY=sk-xxx escli --json models   {DOT} skip login entirely
+""")
+    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,
+                                   epilog=f"""examples:
+  escli auth login                    {DOT} interactive prompt
+  escli auth login --key sk-xxx       {DOT} non-interactive (agents/CI)
+  escli auth login -k sk-xxx -p work  {DOT} named profile
+  echo sk-xxx | escli auth login      {DOT} pipe key from stdin
+
+agent: escli --json auth login --key sk-xxx
+  {ARROW} {{"success": true, "profile": "default", "key": "sk-xxx...xxx", "models": "28 models"}}
+""")
+    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.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.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)
+
+    switch_p = auth_subs.add_parser("switch", aliases=["use"], help="Switch 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,
+                              epilog=f"""subcommands:
+  generate (gen, g)  {DOT} generate image from text prompt
+  edit (e)           {DOT} edit existing image with instruction
+
+quick reference:
+  escli i g "prompt" -s wide -q high --open   {DOT} generate landscape
+  escli i e "instruction" -i img.png --open   {DOT} edit image
+
+sizes: square(1024x1024) landscape(1536x1024) portrait(1024x1536)
+       aliases: sq, wide, tall, land, port, ls
+""")
+    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("-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)")
+        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)")
+        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)")
+        p.add_argument("-m", "--model", default=os.environ.get("ESCLI_IMAGE_MODEL", DEFAULTS["model"]),
+                       help="Model to use (default: gpt-image-2)")
+        p.add_argument("-o", "--output", default=None,
+                       help="Output file path. If omitted, auto-generates: YYYYMMDD-HHMMSS-slugified-prompt.png")
+        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")
+        p.add_argument("--compression", type=int, default=None, metavar="0-100",
+                       help="Output compression level for jpeg/webp (0=min, 100=max)")
+        p.add_argument("--moderation", default=None, choices=["auto", "low"],
+                       help="Content moderation: auto (default) | low (permissive)")
+        if include_input:
+            p.add_argument("-i", "--input", required=True,
+                           help="Path to input image file to edit (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)")
+
+    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):
+  square, sq           {ARROW} 1024x1024   (default)
+  landscape, wide, ls  {ARROW} 1536x1024   (good for wallpapers, banners)
+  portrait, tall, port {ARROW} 1024x1536   (good for phone mockups, posters)
+  1024x1024            {ARROW} also accepts raw WxH values
+
+quality:
+  low     {DOT} fastest (~15s), lower detail
+  medium  {DOT} balanced (~25s)
+  high    {DOT} best quality (~40s), most detail
+
+examples:
+  escli i g "a sunset over the ocean"
+  escli i g "oil painting of a mountain" -s wide -q high --open
+  escli i g "phone app mockup" -s portrait -o mockup.png
+  escli i g "logo design" -f webp --compression 80
+  escli i g "product photo" -s sq -q high -d ./output/
+
+agent examples:
+  escli --json --quiet i g "a logo" -s sq -q low -o /tmp/logo.png
+
+  stdout JSON on success:
+    {{"success": true, "path": "/abs/path/logo.png", "size_bytes": 123456,
+     "elapsed_seconds": 18.4, "prompt": "a logo", "model": "gpt-image-2",
+     "image_size": "1024x1024", "quality": "low",
+     "revised_prompt": "A simple clean logo design..."}}
+
+  stdout JSON on error:
+    {{"success": false, "error": "error message"}}
+""")
+    add_image_flags(gen_p)
+    gen_p.add_argument("--background", default=None, choices=VALID_BACKGROUNDS,
+                       help="Background: auto (default) | transparent (removes background)")
+    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",
+                                   formatter_class=F, epilog=f"""how it works:
+  Takes an input image (-i) and applies the prompt as an edit instruction.
+  The model understands the image content and modifies it accordingly.
+
+examples:
+  escli i e "make it snow" -i summer.jpg --open
+  escli i e "repaint as oil painting" -i photo.jpg -q high -o painted.png
+  escli i e "remove the background" -i product.png
+  escli i e "add sunglasses to the person" -i portrait.jpg -s sq
+
+agent example:
+  escli --json --quiet i e "make it blue" -i input.png -o output.png
+
+  stdout JSON on success:
+    {{"success": true, "path": "/abs/path/output.png", "size_bytes": 123456,
+     "elapsed_seconds": 22.7, "prompt": "make it blue",
+     "input": "/abs/path/input.png", "model": "gpt-image-2",
+     "image_size": "1024x1024", "quality": "high"}}
+
+supported input formats: png, jpg, jpeg, webp
+""")
+    add_image_flags(edit_p, include_input=True)
+    edit_p.set_defaults(func=cmd_image_edit)
+
+    # ── models ────────────────────────────────────────────────────────
+    subs.add_parser("models", aliases=["m"], help="List available models", formatter_class=F,
+                    epilog=f"""lists all models available on the API endpoint.
+
+agent example:
+  escli --json models
+  {ARROW} {{"success": true, "models": ["gpt-image-2", "gpt-5.4-mini", ...], "count": 28}}
+""").set_defaults(func=cmd_models)
+
+    # ── docs (Context7) ──────────────────────────────────────────────
+    from .commands.docs import register as register_docs
+    register_docs(subs)
+
+    # ── audio (AssemblyAI) ───────────────────────────────────────────
+    from .commands.audio import register as register_audio
+    register_audio(subs)
+
+    # ── search + fetch (Parallel.ai) ────────────────────────────────
+    from .commands.search import register as register_search
+    register_search(subs)
+
+    # ── research (Parallel Task API) ────────────────────────────────
+    from .commands.research import register as register_research
+    register_research(subs)
+
+    # ── social (Tavily) ─────────────────────────────────────────────
+    from .commands.social import register as register_social
+    register_social(subs)
+
+    # ── usage (gate analytics) ──────────────────────────────────────
+    from .commands.usage import register as register_usage
+    register_usage(subs)
+
+    # ── version ───────────────────────────────────────────────────────
+    subs.add_parser("version", help="Show version info").set_defaults(func=cmd_version)
+
+    return root
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────────────────────
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+    for attr in ("json", "quiet"):
+        if not hasattr(args, attr): setattr(args, attr, False)
+
+    # Self-description: machine-readable manifest for agent discovery
+    if getattr(args, "describe", False):
+        from .services.describe import generate_manifest
+        import json as _json
+        print(_json.dumps(generate_manifest(parser), indent=2))
+        return 0
+
+    if getattr(args, "version", False) and not args.command: return cmd_version(args)
+    if not args.command: parser.print_help(); return 0
+    if args.command in ("auth", "a") and not getattr(args, "auth_command", None):
+        print(f"  usage: escli auth <login{PIPE}logout{PIPE}status{PIPE}profiles{PIPE}switch>", file=sys.stderr); return 2
+    if args.command in ("image", "img", "i") and not getattr(args, "image_command", None):
+        print(f"  usage: escli image <generate{PIPE}edit>", file=sys.stderr); return 2
+    if args.command in ("docs", "d") and not getattr(args, "docs_command", None):
+        print(f"  usage: escli docs <search{PIPE}get{PIPE}fetch>", file=sys.stderr); return 2
+    if args.command in ("audio", "au") and not getattr(args, "audio_command", None):
+        print(f"  usage: escli audio <transcribe{PIPE}status{PIPE}get{PIPE}list>", file=sys.stderr); return 2
+    if hasattr(args, "func"): return args.func(args)
+    parser.print_help(); return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)