cueapi 0.1.0__py3-none-any.whl

cueapi/__init__.py

@@ -0,0 +1,3 @@
+"""CueAPI CLI — Your Agents' Cue to Act."""
+
+__version__ = "0.1.0"

cueapi/auth.py

@@ -0,0 +1,185 @@
+"""Auth commands: login, logout, whoami, key regenerate."""
+from __future__ import annotations
+
+import secrets
+import string
+import time
+import webbrowser
+from typing import Optional
+
+import click
+
+from cueapi.client import CueAPIClient, UnauthClient
+from cueapi.credentials import (
+    get_profile_info,
+    remove_all_credentials,
+    remove_credentials,
+    resolve_api_base,
+    save_credentials,
+)
+from cueapi.formatting import echo_error, echo_info, echo_success
+
+
+def _generate_device_code() -> str:
+    """Generate a random device code like ABCD-EFGH."""
+    chars = string.ascii_uppercase + string.digits
+    part1 = "".join(secrets.choice(chars) for _ in range(4))
+    part2 = "".join(secrets.choice(chars) for _ in range(4))
+    return f"{part1}-{part2}"
+
+
+def do_login(api_base: Optional[str] = None, profile: str = "default") -> None:
+    """Run the device code login flow."""
+    base = api_base or resolve_api_base(profile=profile)
+    device_code = _generate_device_code()
+
+    with UnauthClient(api_base=base) as client:
+        # Step 1: Create device code
+        resp = client.post("/auth/device-code", json={"device_code": device_code})
+        if resp.status_code != 201:
+            error = resp.json().get("detail", {}).get("error", {})
+            echo_error(error.get("message", f"Failed to create device code (HTTP {resp.status_code})"))
+            return
+
+        data = resp.json()
+        verification_url = data["verification_url"]
+        expires_in = data["expires_in"]
+
+        # Step 2: Open browser
+        click.echo("\nOpening browser to authenticate...")
+        try:
+            webbrowser.open(verification_url)
+        except Exception:
+            pass
+        click.echo(f"If browser doesn't open, visit: {verification_url}\n")
+
+        # Step 3: Poll
+        click.echo("Waiting for authentication...", nl=False)
+        deadline = time.time() + expires_in
+        while time.time() < deadline:
+            time.sleep(2)
+            click.echo(".", nl=False)
+
+            resp = client.post("/auth/device-code/poll", json={"device_code": device_code})
+            if resp.status_code != 200:
+                continue
+
+            poll_data = resp.json()
+            status = poll_data.get("status")
+
+            if status == "approved":
+                api_key = poll_data["api_key"]
+                email = poll_data["email"]
+
+                # Save credentials
+                save_credentials(
+                    profile=profile,
+                    data={
+                        "api_key": api_key,
+                        "email": email,
+                        "api_base": base,
+                    },
+                )
+
+                click.echo()
+                echo_success(f"Authenticated as {email}")
+                click.echo(f"API key stored in credentials file.\n")
+                click.echo(f"Your API key: {api_key}")
+                click.echo("(This is the only time your full key will be shown. Save it if you need it elsewhere.)\n")
+                click.echo('Run `cueapi quickstart` to create your first cue.')
+                return
+
+            if status == "expired":
+                click.echo()
+                echo_error("Device code expired. Run `cueapi login` to try again.")
+                return
+
+        click.echo()
+        echo_error("Login timed out. Run `cueapi login` to try again.")
+
+
+def do_whoami(
+    api_key: Optional[str] = None,
+    profile: Optional[str] = None,
+) -> None:
+    """Show current user info."""
+    profile_name = profile or "default"
+    try:
+        with CueAPIClient(api_key=api_key, profile=profile) as client:
+            resp = client.get("/auth/me")
+            if resp.status_code != 200:
+                echo_error(f"Failed to get user info (HTTP {resp.status_code})")
+                return
+
+            data = resp.json()
+
+            # Get local key prefix
+            prof_info = get_profile_info(profile=profile)
+            key_display = "***"
+            if prof_info and "api_key" in prof_info:
+                key_display = prof_info["api_key"][:7] + "..." + prof_info["api_key"][-4:]
+
+            click.echo()
+            echo_info("Email:", data["email"])
+            echo_info("Plan:", data["plan"].capitalize())
+            echo_info("Active cues:", f"{data['active_cues']} / {data['active_cue_limit']}")
+            echo_info("Executions:", f"{data['executions_this_month']} / {data['monthly_execution_limit']} this month")
+            echo_info("API key:", key_display)
+            echo_info("Profile:", profile_name)
+            echo_info("API base:", client.api_base)
+            click.echo()
+    except click.ClickException:
+        click.echo("Not logged in. Run `cueapi login` to authenticate.")
+
+
+def do_logout(profile: str = "default", logout_all: bool = False) -> None:
+    """Remove credentials."""
+    if logout_all:
+        remove_all_credentials()
+        click.echo("Removed all credentials.")
+        return
+
+    email = remove_credentials(profile=profile)
+    if email:
+        click.echo(f"Removed credentials for {email} ({profile} profile).")
+    else:
+        click.echo(f"No credentials found for profile '{profile}'.")
+
+
+def do_key_regenerate(
+    api_key: Optional[str] = None,
+    profile: Optional[str] = None,
+    skip_confirm: bool = False,
+) -> None:
+    """Regenerate API key."""
+    if not skip_confirm:
+        click.echo()
+        click.echo(click.style("Warning: ", fg="yellow") + "This will instantly revoke your current API key.")
+        click.echo("  All agents using the old key will stop working.\n")
+        if not click.confirm("Proceed?"):
+            click.echo("Cancelled.")
+            return
+
+    try:
+        with CueAPIClient(api_key=api_key, profile=profile) as client:
+            resp = client.post("/auth/key/regenerate")
+            if resp.status_code != 200:
+                echo_error(f"Failed to regenerate key (HTTP {resp.status_code})")
+                return
+
+            data = resp.json()
+            new_key = data["api_key"]
+
+            # Update local credentials
+            profile_name = profile or "default"
+            prof_info = get_profile_info(profile=profile)
+            if prof_info:
+                prof_info["api_key"] = new_key
+                save_credentials(profile=profile_name, data=prof_info)
+
+            click.echo()
+            click.echo(f"New API key: {new_key}")
+            click.echo("(This is the only time this key will be shown.)\n")
+            click.echo("Local credentials updated.")
+    except click.ClickException as e:
+        click.echo(str(e))

cueapi/cli.py

@@ -0,0 +1,468 @@
+"""CueAPI CLI — Click command group and all commands."""
+from __future__ import annotations
+
+import json
+import webbrowser
+from typing import Optional
+
+import click
+
+from cueapi import __version__
+from cueapi.auth import do_key_regenerate, do_login, do_logout, do_whoami
+from cueapi.client import CueAPIClient
+from cueapi.credentials import resolve_api_base
+from cueapi.formatting import (
+    echo_error,
+    echo_info,
+    echo_success,
+    echo_table,
+    format_status,
+)
+from cueapi.quickstart import do_quickstart
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="cueapi")
+@click.option("--api-key", envvar="CUEAPI_API_KEY", default=None, help="API key (overrides credentials file)")
+@click.option("--profile", default=None, help="Credentials profile to use")
+@click.pass_context
+def main(ctx: click.Context, api_key: Optional[str], profile: Optional[str]) -> None:
+    """CueAPI — Your Agents' Cue to Act."""
+    ctx.ensure_object(dict)
+    ctx.obj["api_key"] = api_key
+    ctx.obj["profile"] = profile
+
+
+# --- Auth commands ---
+
+
+@main.command()
+@click.pass_context
+def login(ctx: click.Context) -> None:
+    """Authenticate with CueAPI via browser."""
+    profile = ctx.obj.get("profile") or "default"
+    api_base = resolve_api_base(profile=profile)
+    do_login(api_base=api_base, profile=profile)
+
+
+@main.command()
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """Show current user info."""
+    do_whoami(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile"))
+
+
+@main.command()
+@click.option("--all", "logout_all", is_flag=True, help="Remove all profiles")
+@click.pass_context
+def logout(ctx: click.Context, logout_all: bool) -> None:
+    """Remove stored credentials."""
+    profile = ctx.obj.get("profile") or "default"
+    do_logout(profile=profile, logout_all=logout_all)
+
+
+@main.command()
+@click.pass_context
+def quickstart(ctx: click.Context) -> None:
+    """Guided setup: create a test cue, verify delivery, clean up."""
+    do_quickstart(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile"))
+
+
+# --- Cue commands ---
+
+
+@main.command()
+@click.option("--name", required=True, help="Cue name")
+@click.option("--cron", default=None, help="Cron expression for recurring cue")
+@click.option("--at", "at_time", default=None, help="ISO timestamp for one-time cue")
+@click.option("--url", required=True, help="Callback URL")
+@click.option("--method", default="POST", help="HTTP method (default: POST)")
+@click.option("--timezone", "tz", default="UTC", help="Timezone (default: UTC)")
+@click.option("--payload", default=None, help="JSON payload string")
+@click.option("--description", default=None, help="Cue description")
+@click.pass_context
+def create(
+    ctx: click.Context,
+    name: str,
+    cron: Optional[str],
+    at_time: Optional[str],
+    url: str,
+    method: str,
+    tz: str,
+    payload: Optional[str],
+    description: Optional[str],
+) -> None:
+    """Create a new cue."""
+    if cron and at_time:
+        raise click.UsageError("Cannot use both --cron and --at. Choose one.")
+    if not cron and not at_time:
+        raise click.UsageError("Must specify either --cron or --at.")
+
+    schedule = {"timezone": tz}
+    if cron:
+        schedule["type"] = "recurring"
+        schedule["cron"] = cron
+    else:
+        schedule["type"] = "once"
+        schedule["at"] = at_time
+
+    body = {
+        "name": name,
+        "schedule": schedule,
+        "callback": {"url": url, "method": method},
+    }
+
+    if payload:
+        try:
+            body["payload"] = json.loads(payload)
+        except json.JSONDecodeError:
+            raise click.UsageError("--payload must be valid JSON")
+
+    if description:
+        body["description"] = description
+
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.post("/cues", json=body)
+            if resp.status_code == 201:
+                cue = resp.json()
+                click.echo()
+                echo_success(f"Created: {cue['id']}")
+                echo_info("Status:", cue["status"])
+                if cue.get("next_run"):
+                    echo_info("Next run:", cue["next_run"])
+                click.echo()
+            elif resp.status_code == 403:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", "Cue limit exceeded"))
+                click.echo("\nRun `cueapi upgrade` to increase your limit.")
+            else:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed (HTTP {resp.status_code})"))
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command(name="list")
+@click.option("--status", default=None, help="Filter by status (active/paused)")
+@click.option("--limit", default=20, type=int, help="Max results")
+@click.option("--offset", default=0, type=int, help="Offset for pagination")
+@click.pass_context
+def list_cues(ctx: click.Context, status: Optional[str], limit: int, offset: int) -> None:
+    """List your cues."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            params = {"limit": limit, "offset": offset}
+            if status:
+                params["status"] = status
+
+            resp = client.get("/cues", params=params)
+            if resp.status_code != 200:
+                echo_error(f"Failed to list cues (HTTP {resp.status_code})")
+                return
+
+            data = resp.json()
+            cues = data.get("cues", [])
+            total = data.get("total", len(cues))
+
+            if not cues:
+                click.echo("\nNo cues yet. Create your first one:")
+                click.echo('  cueapi create --name "my-cue" --cron "0 9 * * *" --url https://my-agent.com/webhook')
+                click.echo('\nOr run `cueapi quickstart` for guided setup.\n')
+                return
+
+            click.echo()
+            rows = []
+            for c in cues:
+                next_run = c.get("next_run", "—") or "—"
+                if next_run != "—":
+                    # Truncate to minute precision
+                    next_run = next_run[:16].replace("T", " ") + " UTC"
+                rows.append([c["id"], c["name"], format_status(c["status"]), next_run])
+
+            echo_table(
+                ["ID", "NAME", "STATUS", "NEXT RUN"],
+                rows,
+                widths=[22, 20, 12, 22],
+            )
+
+            # Summary
+            active = sum(1 for c in cues if c["status"] == "active")
+            paused = sum(1 for c in cues if c["status"] == "paused")
+            parts = []
+            if active:
+                parts.append(f"{active} active")
+            if paused:
+                parts.append(f"{paused} paused")
+            other = total - active - paused
+            if other > 0:
+                parts.append(f"{other} other")
+            click.echo(f"\n{total} cues ({', '.join(parts)})\n")
+
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.argument("cue_id")
+@click.pass_context
+def get(ctx: click.Context, cue_id: str) -> None:
+    """Get detailed info about a cue."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.get(f"/cues/{cue_id}")
+            if resp.status_code == 404:
+                echo_error(f"Cue not found: {cue_id}")
+                return
+            if resp.status_code != 200:
+                echo_error(f"Failed (HTTP {resp.status_code})")
+                return
+
+            c = resp.json()
+            click.echo()
+            echo_info("Name:", c["name"])
+            echo_info("Status:", format_status(c["status"]))
+
+            sched = c.get("schedule", {})
+            if sched.get("cron"):
+                echo_info("Schedule:", f"{sched['cron']} ({sched.get('timezone', 'UTC')})")
+            elif sched.get("at"):
+                echo_info("Schedule:", f"One-time: {sched['at']}")
+
+            cb = c.get("callback", {})
+            echo_info("Callback:", f"{cb.get('method', 'POST')} {cb.get('url', '')}")
+
+            if c.get("next_run"):
+                echo_info("Next run:", c["next_run"])
+            if c.get("last_run"):
+                echo_info("Last run:", c["last_run"])
+
+            echo_info("Run count:", str(c.get("run_count", 0)))
+            echo_info("Created:", c["created_at"])
+
+            if c.get("description"):
+                echo_info("Description:", c["description"])
+
+            # Display recent executions
+            executions = c.get("executions", [])
+            if executions:
+                click.echo()
+                click.echo("Recent executions:")
+                for ex in executions:
+                    ts = ex.get("scheduled_for", "")[:16].replace("T", " ")
+                    status = ex.get("status", "")
+                    if status == "success":
+                        mark = click.style("success", fg="green")
+                        detail = f"({ex.get('http_status', '')}, {ex.get('attempts', 0)} attempt{'s' if ex.get('attempts', 0) != 1 else ''})"
+                    elif status == "failed":
+                        mark = click.style("failed", fg="red")
+                        err = ex.get("error_message") or f"HTTP {ex.get('http_status', '?')}"
+                        detail = f"({err}, {ex.get('attempts', 0)} attempts)"
+                    else:
+                        mark = click.style(status, fg="yellow")
+                        detail = f"({ex.get('attempts', 0)} attempts)"
+                    click.echo(f"  {ts}  {mark}  {detail}")
+
+            click.echo()
+
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.argument("cue_id")
+@click.pass_context
+def pause(ctx: click.Context, cue_id: str) -> None:
+    """Pause a cue."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.patch(f"/cues/{cue_id}", json={"status": "paused"})
+            if resp.status_code == 200:
+                c = resp.json()
+                echo_success(f"Paused: {cue_id} ({c['name']})")
+            elif resp.status_code == 404:
+                echo_error(f"Cue not found: {cue_id}")
+            else:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed (HTTP {resp.status_code})"))
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.argument("cue_id")
+@click.pass_context
+def resume(ctx: click.Context, cue_id: str) -> None:
+    """Resume a paused cue."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.patch(f"/cues/{cue_id}", json={"status": "active"})
+            if resp.status_code == 200:
+                c = resp.json()
+                echo_success(f"Resumed: {cue_id} ({c['name']})")
+                if c.get("next_run"):
+                    echo_info("Next run:", c["next_run"])
+            elif resp.status_code == 404:
+                echo_error(f"Cue not found: {cue_id}")
+            else:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed (HTTP {resp.status_code})"))
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.argument("cue_id")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+def delete(ctx: click.Context, cue_id: str, yes: bool) -> None:
+    """Delete a cue."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            # Get cue name for confirmation
+            if not yes:
+                resp = client.get(f"/cues/{cue_id}")
+                if resp.status_code == 404:
+                    echo_error(f"Cue not found: {cue_id}")
+                    return
+                name = resp.json().get("name", "unknown")
+                if not click.confirm(f"Delete {cue_id} ({name})?"):
+                    click.echo("Cancelled.")
+                    return
+
+            resp = client.delete(f"/cues/{cue_id}")
+            if resp.status_code == 204:
+                click.echo("Deleted.")
+            elif resp.status_code == 404:
+                echo_error(f"Cue not found: {cue_id}")
+            else:
+                echo_error(f"Failed (HTTP {resp.status_code})")
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+# --- Billing commands ---
+
+
+@main.command()
+@click.pass_context
+def upgrade(ctx: click.Context) -> None:
+    """Upgrade your plan via Stripe Checkout."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            # Show current plan
+            resp = client.get("/usage")
+            if resp.status_code == 200:
+                data = resp.json()
+                plan = data.get("plan", {})
+                click.echo(f"\nCurrent plan: {plan.get('name', 'Free').capitalize()}\n")
+
+            click.echo("Available plans:")
+            click.echo("  Pro    $9.99/mo   100 cues, 5,000 executions/mo")
+            click.echo("  Scale  $49/mo     500 cues, 50,000 executions/mo\n")
+
+            plan_choice = click.prompt("Which plan?", type=click.Choice(["pro", "scale"]))
+            interval = click.prompt("Billing interval?", type=click.Choice(["monthly", "annual"]), default="monthly")
+
+            resp = client.post("/billing/checkout", json={"plan": plan_choice, "interval": interval})
+            if resp.status_code == 200:
+                url = resp.json().get("checkout_url")
+                if url:
+                    click.echo("\nOpening checkout...")
+                    try:
+                        webbrowser.open(url)
+                    except Exception:
+                        pass
+                    click.echo(f"If browser doesn't open, visit: {url}")
+            else:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed (HTTP {resp.status_code})"))
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.pass_context
+def manage(ctx: click.Context) -> None:
+    """Open Stripe billing portal."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.post("/billing/portal")
+            if resp.status_code == 200:
+                url = resp.json().get("portal_url")
+                if url:
+                    click.echo("Opening billing portal...")
+                    try:
+                        webbrowser.open(url)
+                    except Exception:
+                        pass
+                    click.echo(f"If browser doesn't open, visit: {url}")
+            else:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed (HTTP {resp.status_code})"))
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+@main.command()
+@click.pass_context
+def usage(ctx: click.Context) -> None:
+    """Show current usage stats."""
+    try:
+        with CueAPIClient(api_key=ctx.obj.get("api_key"), profile=ctx.obj.get("profile")) as client:
+            resp = client.get("/usage")
+            if resp.status_code != 200:
+                echo_error(f"Failed (HTTP {resp.status_code})")
+                return
+
+            data = resp.json()
+            plan = data.get("plan", {})
+            cues = data.get("cues", {})
+            execs = data.get("executions", {})
+            rate = data.get("rate_limit", {})
+
+            click.echo()
+            echo_info("Plan:", plan.get("name", "free").capitalize())
+
+            active = cues.get("active", 0)
+            cue_limit = cues.get("limit", 10)
+            echo_info("Active cues:", f"{active} / {cue_limit}")
+
+            used = execs.get("used", 0)
+            exec_limit = execs.get("limit", 300)
+            pct = (used / exec_limit * 100) if exec_limit > 0 else 0
+            echo_info("Executions:", f"{used:,} / {exec_limit:,} ({pct:.1f}%)")
+
+            echo_info("Rate limit:", f"{rate.get('limit', 60)} req/min")
+            click.echo()
+
+    except click.ClickException as e:
+        click.echo(str(e))
+
+
+# --- Key management ---
+
+
+@main.group()
+def key() -> None:
+    """API key management."""
+    pass
+
+
+@key.command()
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+def regenerate(ctx: click.Context, yes: bool) -> None:
+    """Regenerate your API key (revokes current key)."""
+    do_key_regenerate(
+        api_key=ctx.obj.get("api_key"),
+        profile=ctx.obj.get("profile"),
+        skip_confirm=yes,
+    )
+
+
+main.add_command(key)
+
+
+if __name__ == "__main__":
+    main()

cueapi/client.py

@@ -0,0 +1,77 @@
+"""HTTP client wrapper for CueAPI."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from cueapi.credentials import resolve_api_base, resolve_api_key
+
+
+class CueAPIClient:
+    """Thin wrapper around httpx for CueAPI requests."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_base: Optional[str] = None,
+        profile: Optional[str] = None,
+    ):
+        self.api_key = api_key or resolve_api_key(profile=profile)
+        self.api_base = (api_base or resolve_api_base(profile=profile)).rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.api_base,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.get(path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.post(path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.patch(path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.delete(path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "CueAPIClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class UnauthClient:
+    """Client for unauthenticated endpoints (login, echo store)."""
+
+    def __init__(self, api_base: Optional[str] = None):
+        self.api_base = (api_base or "https://api.cueapi.ai/v1").rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.api_base,
+            headers={"Content-Type": "application/json"},
+            timeout=30.0,
+        )
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.get(path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._client.post(path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "UnauthClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

cueapi/credentials.py

@@ -0,0 +1,139 @@
+"""Credential storage and resolution for CueAPI CLI."""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import stat
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import click
+
+
+def _default_creds_path() -> Path:
+    """Get the default credentials file path based on OS."""
+    system = platform.system()
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "cueapi" / "credentials.json"
+
+
+CREDS_PATH = _default_creds_path()
+
+
+def load_credentials(creds_file: Optional[Path] = None) -> Dict[str, Any]:
+    """Load credentials from file. Returns empty dict if file doesn't exist."""
+    path = creds_file or CREDS_PATH
+    if not path.exists():
+        return {}
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_credentials(
+    creds_file: Optional[Path] = None,
+    profile: str = "default",
+    data: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Save credentials for a profile. Creates parent directories if needed."""
+    path = creds_file or CREDS_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    creds = load_credentials(path)
+    if data:
+        creds[profile] = data
+
+    with open(path, "w") as f:
+        json.dump(creds, f, indent=2)
+
+    # Set file permissions to 600 (owner read/write only)
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass  # Windows may not support chmod
+
+
+def remove_credentials(
+    creds_file: Optional[Path] = None,
+    profile: str = "default",
+) -> Optional[str]:
+    """Remove a profile from credentials. Returns email if found."""
+    path = creds_file or CREDS_PATH
+    creds = load_credentials(path)
+    if profile not in creds:
+        return None
+
+    email = creds[profile].get("email", "unknown")
+    del creds[profile]
+
+    with open(path, "w") as f:
+        json.dump(creds, f, indent=2)
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    return email
+
+
+def remove_all_credentials(creds_file: Optional[Path] = None) -> None:
+    """Delete the entire credentials file."""
+    path = creds_file or CREDS_PATH
+    if path.exists():
+        path.unlink()
+
+
+def resolve_api_key(
+    api_key: Optional[str] = None,
+    profile: Optional[str] = None,
+    creds_file: Optional[Path] = None,
+) -> str:
+    """Resolve API key from env var, flag, or credentials file.
+
+    Priority: CUEAPI_API_KEY env > --api-key flag > profile from file.
+    """
+    env_key = os.environ.get("CUEAPI_API_KEY")
+    if env_key:
+        return env_key
+
+    if api_key:
+        return api_key
+
+    profile_name = profile or os.environ.get("CUEAPI_PROFILE", "default")
+    creds = load_credentials(creds_file)
+    if profile_name in creds:
+        return creds[profile_name]["api_key"]
+
+    raise click.ClickException(
+        "Not logged in. Run `cueapi login` to authenticate."
+    )
+
+
+def resolve_api_base(
+    profile: Optional[str] = None,
+    creds_file: Optional[Path] = None,
+) -> str:
+    """Resolve API base URL from credentials or default."""
+    env_base = os.environ.get("CUEAPI_API_BASE")
+    if env_base:
+        return env_base
+
+    profile_name = profile or os.environ.get("CUEAPI_PROFILE", "default")
+    creds = load_credentials(creds_file)
+    if profile_name in creds:
+        return creds[profile_name].get("api_base", "https://api.cueapi.ai/v1")
+
+    return "https://api.cueapi.ai/v1"
+
+
+def get_profile_info(
+    profile: Optional[str] = None,
+    creds_file: Optional[Path] = None,
+) -> Optional[Dict[str, Any]]:
+    """Get full profile data. Returns None if not found."""
+    profile_name = profile or os.environ.get("CUEAPI_PROFILE", "default")
+    creds = load_credentials(creds_file)
+    return creds.get(profile_name)

cueapi/formatting.py

@@ -0,0 +1,82 @@
+"""Terminal output formatting helpers."""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+
+def echo_error(message: str) -> None:
+    """Print an error message."""
+    import click
+    click.echo(click.style(f"Error: {message}", fg="red"), err=True)
+
+
+def echo_success(message: str) -> None:
+    """Print a success message."""
+    import click
+    click.echo(click.style(message, fg="green"))
+
+
+def echo_warning(message: str) -> None:
+    """Print a warning message."""
+    import click
+    click.echo(click.style(message, fg="yellow"))
+
+
+def echo_info(label: str, value: str, label_width: int = 16) -> None:
+    """Print a label: value pair."""
+    import click
+    click.echo(f"{label:<{label_width}} {value}")
+
+
+def echo_json(data: Any, indent: int = 2) -> None:
+    """Pretty-print JSON data."""
+    import click
+    click.echo(json.dumps(data, indent=indent))
+
+
+def echo_table(headers: List[str], rows: List[List[str]], widths: Optional[List[int]] = None) -> None:
+    """Print a simple table with headers and rows."""
+    import click
+
+    if widths is None:
+        widths = []
+        for i, h in enumerate(headers):
+            col_max = len(h)
+            for row in rows:
+                if i < len(row):
+                    col_max = max(col_max, len(str(row[i])))
+            widths.append(min(col_max + 2, 40))
+
+    # Header
+    header_line = ""
+    for i, h in enumerate(headers):
+        header_line += f"{h:<{widths[i]}}"
+    click.echo(click.style(header_line, bold=True))
+
+    # Rows
+    for row in rows:
+        line = ""
+        for i, cell in enumerate(row):
+            if i < len(widths):
+                line += f"{str(cell):<{widths[i]}}"
+            else:
+                line += str(cell)
+        click.echo(line)
+
+
+def format_status(status: str) -> str:
+    """Format a status string with color."""
+    colors = {
+        "active": "green",
+        "paused": "yellow",
+        "completed": "cyan",
+        "failed": "red",
+        "success": "green",
+        "pending": "yellow",
+        "delivering": "yellow",
+        "retrying": "yellow",
+    }
+    import click
+    color = colors.get(status, "white")
+    return click.style(status, fg=color)

cueapi/quickstart.py

@@ -0,0 +1,113 @@
+"""Quickstart command — guided first-cue setup."""
+from __future__ import annotations
+
+import secrets
+import time
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import click
+
+from cueapi.client import CueAPIClient
+from cueapi.formatting import echo_error, echo_json, echo_success
+
+
+def do_quickstart(
+    api_key: Optional[str] = None,
+    profile: Optional[str] = None,
+) -> None:
+    """Run the quickstart flow: create test cue, verify delivery, clean up."""
+    try:
+        with CueAPIClient(api_key=api_key, profile=profile) as client:
+            click.echo("\nSetting up your first cue...\n")
+
+            # Generate unique echo token
+            echo_token = f"qs-{secrets.token_hex(8)}"
+
+            # Step 1: Create one-time cue scheduled for NOW + 15s
+            scheduled_time = datetime.now(timezone.utc) + timedelta(seconds=15)
+            scheduled_iso = scheduled_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+            # The callback URL posts to the echo endpoint
+            callback_url = f"{client.api_base}/echo/{echo_token}"
+
+            click.echo("Step 1: Creating a test cue (fires in 15 seconds)...")
+            resp = client.post("/cues", json={
+                "name": "quickstart-test",
+                "description": "Quickstart test cue — safe to delete",
+                "schedule": {
+                    "type": "once",
+                    "at": scheduled_iso,
+                    "timezone": "UTC",
+                },
+                "callback": {
+                    "url": callback_url,
+                    "method": "POST",
+                },
+                "payload": {"message": "Your first cue! CueAPI is working."},
+            })
+
+            if resp.status_code != 201:
+                error = resp.json().get("detail", {}).get("error", {})
+                echo_error(error.get("message", f"Failed to create cue (HTTP {resp.status_code})"))
+                return
+
+            cue = resp.json()
+            cue_id = cue["id"]
+            click.echo(f"        Created: {cue_id}")
+            click.echo(f"        Scheduled for: {scheduled_iso}\n")
+
+            # Step 2: Wait for delivery
+            click.echo("Step 2: Waiting for delivery...")
+            deadline = time.time() + 60
+            delivered = False
+            last_countdown = 15
+
+            while time.time() < deadline:
+                remaining = max(0, int(scheduled_time.timestamp() - time.time()))
+                if remaining > 0 and remaining < last_countdown:
+                    click.echo(f"        {remaining}s...", nl=False)
+                    click.echo("\r", nl=False)
+                    last_countdown = remaining
+
+                time.sleep(2)
+
+                # Poll echo endpoint
+                resp = client.get(f"/echo/{echo_token}")
+                if resp.status_code == 200:
+                    data = resp.json()
+                    if data.get("status") == "delivered":
+                        click.echo("                              ")  # Clear countdown
+                        echo_success("        Callback delivered!\n")
+                        click.echo("        Payload:")
+                        echo_json(data["payload"])
+                        click.echo()
+                        delivered = True
+                        break
+
+            if not delivered:
+                click.echo()
+                echo_error("Timed out waiting for delivery.")
+                click.echo("\nTroubleshooting:")
+                click.echo("  - Is the poller running? (`python -m worker.poller`)")
+                click.echo("  - Is the arq worker running? (`python -m worker.main`)")
+                click.echo(f"\n  Test cue ID: {cue_id}")
+                click.echo(f"  Echo token: {echo_token}")
+                return
+
+            # Step 3: Clean up
+            click.echo("Step 3: Cleaning up test cue...")
+            resp = client.delete(f"/cues/{cue_id}")
+            if resp.status_code == 204:
+                click.echo("        Deleted.\n")
+            else:
+                click.echo(f"        (cleanup: HTTP {resp.status_code})\n")
+
+            click.echo("CueAPI is working!\n")
+            click.echo("Next steps:")
+            click.echo('  cueapi create --name "my-cue" --cron "0 9 * * *" --url https://my-agent.com/webhook')
+            click.echo("  Docs: https://docs.cueapi.ai")
+            click.echo()
+
+    except click.ClickException as e:
+        click.echo(str(e))

cueapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: cueapi
+Version: 0.1.0
+Summary: CLI for CueAPI — Your Agents' Cue to Act. The scheduling API for AI agents.
+Author-email: "Vector Apps Inc." <hello@cueapi.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://cueapi.ai
+Project-URL: Repository, https://github.com/govindkavaturi-art/cueapi-cli
+Keywords: cueapi,ai-agents,scheduling,webhook,cron,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# CueAPI CLI
+
+The official command-line interface for [CueAPI](https://cueapi.ai) — Your Agents' Cue to Act.
+
+CueAPI is a scheduling API for AI agents. Agents register cues (scheduled tasks), CueAPI fires webhooks at the right time. No cron jobs. No infrastructure.
+
+## Install
+
+```bash
+pip install cueapi
+```
+
+## Quick Start
+
+```bash
+cueapi login
+cueapi quickstart
+cueapi create --name "morning-check" --cron "0 9 * * *" --url https://my-agent.com/webhook
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `cueapi login` | Authenticate and store API key |
+| `cueapi whoami` | Show current user and plan |
+| `cueapi logout` | Remove local credentials |
+| `cueapi quickstart` | Guided first-cue setup |
+| `cueapi create` | Create a new cue |
+| `cueapi list` | List all cues |
+| `cueapi get <id>` | Get cue details |
+| `cueapi pause <id>` | Pause a cue |
+| `cueapi resume <id>` | Resume a cue |
+| `cueapi delete <id>` | Delete a cue |
+| `cueapi upgrade` | Open billing |
+| `cueapi usage` | Show current usage |
+| `cueapi key regenerate` | Regenerate API key |
+
+## Auth
+
+Credentials stored in `~/.config/cueapi/credentials.json`.
+
+Override: `export CUEAPI_API_KEY=cue_sk_your_key` or `--api-key` flag.
+
+## Links
+
+- [Website](https://cueapi.ai)
+- [API Reference](https://cueapi.ai/api)
+- [Pricing](https://cueapi.ai/pricing)
+
+## License
+
+MIT — Built by [Vector Apps Inc.](https://vectorapps.com)

cueapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cueapi/__init__.py,sha256=IbfT1t7l5aQq62NU5lL42A8t62bUfgWoDSzWBr2Qtdk,69
+cueapi/auth.py,sha256=FP7_vJG5i7uJLjgiUzLdpItgZN2wYRrdxs44fG8SSco,6585
+cueapi/cli.py,sha256=2SN1gTA4vezd8uynOzuTKB-baMc0ebcaAkn0H4O3yd8,17024
+cueapi/client.py,sha256=KI-AH0mcw9-N-mqb25pz3kxnY-YVXsZQQQvETReARuQ,2293
+cueapi/credentials.py,sha256=hEgtAR6o6adWftCfIj2Y3NVlnPHVOB0kmuReKtiCYk8,3893
+cueapi/formatting.py,sha256=FNOL3_AqS1S4YaFnT_bjBeA8AicEfz7zVBcz4XhGimc,2220
+cueapi/quickstart.py,sha256=MP-VLG4MOOCMuwOvGrzLPtj4xk6VqRmS0ybHKWO8IQA,4469
+cueapi-0.1.0.dist-info/licenses/LICENSE,sha256=NTPnT6pMYtxSQeYVmnLrpTzndyDc6bIw5AgaWeTzirc,1073
+cueapi-0.1.0.dist-info/METADATA,sha256=K5q8VKxINDIGfRDRcSh4u5qZBGqcItl-USN_d0e7WyM,2166
+cueapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cueapi-0.1.0.dist-info/entry_points.txt,sha256=2Ev2SY8FlOuiCx7Ytvp3hnxCRJTM8TE8do8cWZAk7dk,43
+cueapi-0.1.0.dist-info/top_level.txt,sha256=lnExE-IhJePLTBluRyU1sNrssIuiCZfL2kvCLbyJMgo,7
+cueapi-0.1.0.dist-info/RECORD,,

cueapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cueapi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cueapi = cueapi.cli:main

cueapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vector Apps Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cueapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cueapi