heyarchie-cli 0.1.0__py3-none-any.whl

archie_cli/__init__.py

@@ -0,0 +1,12 @@
+"""Archie Connect CLI — `archie` console script.
+
+Surfaces the Connect platform as terminal commands. Read-friendly when
+attached to a TTY (rich-rendered tables, colors); machine-friendly when
+piped (`--json`).
+
+Auth is bearer-only today: an Archie session JWT or an Archie OAuth JWT.
+WorkOS-managed `sk_*` API keys are not yet validated server-side — see
+`docs/connect/api-keys-flow.md` for the architectural decision pending.
+"""
+
+__version__ = "0.1.0"

archie_cli/__main__.py

@@ -0,0 +1,35 @@
+"""``archie`` console-script entry point."""
+
+from __future__ import annotations
+
+import click
+
+from archie_cli import __version__
+from archie_cli.cmds.login import login_cmd
+from archie_cli.cmds.skills import skills_group
+from archie_cli.cmds.workstreams import workstreams_group
+
+
+@click.group(
+    help=(
+        "Archie Connect CLI.\n\n"
+        "Read-friendly when attached to a TTY; pipe-friendly with --json.\n"
+        "Auth: bearer token via --api-key, env ARCHIE_API_KEY, or `archie login`."
+    )
+)
+@click.version_option(__version__, prog_name="archie")
+def cli() -> None:
+    """archie — Connect CLI."""
+
+
+cli.add_command(login_cmd)
+cli.add_command(skills_group)
+cli.add_command(workstreams_group)
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

archie_cli/auth.py

@@ -0,0 +1,101 @@
+"""Credential storage for the `archie` CLI.
+
+Lookup order: explicit flag → env var → on-disk credentials → prompt the
+user. The on-disk file at ``~/.archie/credentials.toml`` is chmod 600.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib  # py311+
+except ImportError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+CREDENTIALS_PATH = Path.home() / ".archie" / "credentials.toml"
+DEFAULT_PROFILE = "default"
+DEFAULT_API_URL = "https://api.heyarchie.ai"
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """Resolved CLI credentials."""
+
+    api_url: str
+    api_key: str
+    profile: str
+
+
+class CredentialError(Exception):
+    """Raised when credentials are missing or unreadable."""
+
+
+def load_credentials(
+    *,
+    profile: str = DEFAULT_PROFILE,
+    api_url_override: str | None = None,
+    api_key_override: str | None = None,
+) -> Credentials:
+    """Resolve credentials, preferring explicit overrides → env → on-disk."""
+    api_url = (
+        api_url_override
+        or os.environ.get("ARCHIE_API_URL")
+        or _from_disk(profile, "api_url")
+        or DEFAULT_API_URL
+    )
+    api_key = api_key_override or os.environ.get("ARCHIE_API_KEY") or _from_disk(profile, "api_key")
+    if not api_key:
+        raise CredentialError(
+            "No API key found. Set ARCHIE_API_KEY, run `archie login`, or pass --api-key."
+        )
+    return Credentials(api_url=api_url.rstrip("/"), api_key=api_key, profile=profile)
+
+
+def save_credentials(api_url: str, api_key: str, *, profile: str = DEFAULT_PROFILE) -> Path:
+    """Persist credentials to ``~/.archie/credentials.toml`` (chmod 600)."""
+    CREDENTIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    existing: dict[str, dict[str, str]] = {}
+    if CREDENTIALS_PATH.exists():
+        try:
+            with CREDENTIALS_PATH.open("rb") as fh:
+                existing = tomllib.load(fh)  # type: ignore[assignment]
+        except Exception:  # pragma: no cover — corrupt file → overwrite
+            existing = {}
+    existing[profile] = {"api_url": api_url.rstrip("/"), "api_key": api_key}
+    text = _render_toml(existing)
+    CREDENTIALS_PATH.write_text(text)
+    os.chmod(CREDENTIALS_PATH, stat.S_IRUSR | stat.S_IWUSR)
+    return CREDENTIALS_PATH
+
+
+def _from_disk(profile: str, key: str) -> str | None:
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        with CREDENTIALS_PATH.open("rb") as fh:
+            data = tomllib.load(fh)
+    except Exception as exc:  # pragma: no cover
+        print(f"warning: failed to read {CREDENTIALS_PATH}: {exc}", file=sys.stderr)
+        return None
+    section = data.get(profile)
+    if not isinstance(section, dict):
+        return None
+    value = section.get(key)
+    return str(value) if value else None
+
+
+def _render_toml(data: dict[str, dict[str, str]]) -> str:
+    out: list[str] = []
+    for profile, fields in sorted(data.items()):
+        out.append(f"[{profile}]")
+        for k in sorted(fields):
+            v = fields[k].replace('"', '\\"')
+            out.append(f'{k} = "{v}"')
+        out.append("")
+    return "\n".join(out)

archie_cli/client.py

@@ -0,0 +1,179 @@
+"""HTTP client wrapper around the Archie Connect REST surface.
+
+Handles bearer auth, response envelope unwrapping, and SSE streaming
+for cycle event tails. Async — use via ``asyncio.run`` from each click
+command (the click group is sync; commands hop into asyncio).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from archie_cli.auth import Credentials
+
+
+class ArchieAPIError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: dict[str, Any] | str):
+        self.status_code = status_code
+        self.body = body
+        # Pull out the canonical error envelope shape if present.
+        message = ""
+        if isinstance(body, dict):
+            err = body.get("error") or {}
+            if isinstance(err, dict):
+                message = err.get("message") or err.get("code") or ""
+            else:
+                message = str(err)
+        if not message:
+            message = str(body)[:200]
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class ArchieClient:
+    """Thin async wrapper over httpx.AsyncClient.
+
+    One client per command invocation; opens + closes around the call.
+    """
+
+    def __init__(self, creds: Credentials, *, timeout: float = 30.0):
+        self._creds = creds
+        self._timeout = timeout
+
+    async def __aenter__(self) -> ArchieClient:
+        self._client = httpx.AsyncClient(
+            base_url=self._creds.api_url,
+            timeout=self._timeout,
+            headers={
+                "Authorization": f"Bearer {self._creds.api_key}",
+                "User-Agent": f"heyarchie-cli/0.1.0 ({httpx.__version__})",
+                "Accept": "application/json",
+            },
+        )
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self._client.aclose()
+
+    async def invoke_skill(self, slug: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST /api/v1/skills/{slug}/invoke and return the parsed JSON body."""
+        resp = await self._client.post(
+            f"/api/v1/skills/{slug}/invoke",
+            json=payload,
+        )
+        return self._unwrap(resp)
+
+    async def workstreams_list(
+        self,
+        *,
+        scope: str | None = None,
+        status: str | None = None,
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"limit": limit}
+        if scope:
+            payload["scope"] = scope
+        if status:
+            payload["status"] = status
+        if cursor:
+            payload["cursor"] = cursor
+        return await self.invoke_skill("workstream.list", payload)
+
+    async def workstreams_describe(self, workstream_id: str) -> dict[str, Any]:
+        return await self.invoke_skill("workstream.describe", {"workstream_id": workstream_id})
+
+    async def workstreams_run(
+        self,
+        workstream_id: str,
+        *,
+        client_id: str | None = None,
+        period: str | None = None,
+        runtime_vars: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"workstream_id": workstream_id}
+        if client_id:
+            payload["client_id"] = client_id
+        if period:
+            payload["period"] = period
+        if runtime_vars:
+            payload["runtime_vars"] = runtime_vars
+        if idempotency_key:
+            payload["idempotency_key"] = idempotency_key
+        return await self.invoke_skill("workstream.run", payload)
+
+    async def workstreams_status(self, cycle_id: str) -> dict[str, Any]:
+        return await self.invoke_skill("workstream.status", {"cycle_id": cycle_id})
+
+    async def workstreams_cancel(
+        self,
+        cycle_id: str,
+        *,
+        reason: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"cycle_id": cycle_id}
+        if reason:
+            payload["reason"] = reason
+        if idempotency_key:
+            payload["idempotency_key"] = idempotency_key
+        return await self.invoke_skill("workstream.cancel", payload)
+
+    async def workstreams_events(self, cycle_id: str) -> AsyncIterator[dict[str, Any]]:
+        """Stream SSE events from /api/v1/workstreams/cycles/{cycle_id}/events.
+
+        Yields one parsed JSON dict per SSE ``data:`` line. Filters out
+        comments and empty keepalives. Re-raises on transport failure.
+        """
+        url = f"/api/v1/workstreams/cycles/{cycle_id}/events"
+        async with self._client.stream(
+            "GET",
+            url,
+            headers={"Accept": "text/event-stream"},
+            timeout=httpx.Timeout(60.0, read=None),
+        ) as resp:
+            if resp.status_code >= 400:
+                body = await resp.aread()
+                try:
+                    parsed: dict[str, Any] | str = json.loads(body)
+                except Exception:
+                    parsed = body.decode("utf-8", errors="replace")
+                raise ArchieAPIError(resp.status_code, parsed)
+            buffer: list[str] = []
+            async for line in resp.aiter_lines():
+                if line == "" and buffer:
+                    payload = "\n".join(buffer)
+                    buffer = []
+                    if not payload.startswith("data:"):
+                        continue
+                    data = payload[len("data:") :].strip()
+                    if not data:
+                        continue
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        yield {"raw": data}
+                elif line.startswith(":"):
+                    # SSE comment / keepalive
+                    continue
+                else:
+                    buffer.append(line)
+
+    @staticmethod
+    def _unwrap(resp: httpx.Response) -> dict[str, Any]:
+        try:
+            body = resp.json()
+        except Exception:
+            body = resp.text
+        if resp.status_code >= 400:
+            raise ArchieAPIError(resp.status_code, body)
+        # Connect skill responses wrap the typed output under `output`.
+        if isinstance(body, dict) and "output" in body and isinstance(body["output"], dict):
+            return body["output"]
+        return body if isinstance(body, dict) else {"_raw": body}

archie_cli/cmds/__init__.py

@@ -0,0 +1 @@
+"""Click subcommand groups for the `archie` CLI."""

archie_cli/cmds/login.py

@@ -0,0 +1,46 @@
+"""``archie login`` — paste an API key, persist to ~/.archie/credentials.toml."""
+
+from __future__ import annotations
+
+import click
+
+from archie_cli.auth import (
+    DEFAULT_API_URL,
+    DEFAULT_PROFILE,
+    save_credentials,
+)
+
+
+@click.command("login")
+@click.option(
+    "--api-url",
+    default=DEFAULT_API_URL,
+    show_default=True,
+    help="API base URL. Override for staging or self-hosted tiers.",
+)
+@click.option(
+    "--api-key",
+    default=None,
+    help="Paste here, or omit and we'll prompt without echoing.",
+)
+@click.option(
+    "--profile",
+    default=DEFAULT_PROFILE,
+    show_default=True,
+    help="Save under a named profile (e.g. dev, staging).",
+)
+def login_cmd(api_url: str, api_key: str | None, profile: str) -> None:
+    """Save an API key to ~/.archie/credentials.toml.
+
+    Today this expects an Archie session JWT or Archie OAuth JWT (sent as
+    a Bearer token). WorkOS-issued `sk_*` keys are not yet validated
+    server-side — see docs/connect/api-keys-flow.md.
+    """
+    if not api_key:
+        api_key = click.prompt("API key", hide_input=True, confirmation_prompt=False)
+    api_key = api_key.strip()
+    if not api_key:
+        raise click.ClickException("API key cannot be empty.")
+    path = save_credentials(api_url=api_url, api_key=api_key, profile=profile)
+    click.echo(f"Saved credentials to {path} (profile={profile!r}).")
+    click.echo("Try: archie workstreams list")

archie_cli/cmds/skills.py

@@ -0,0 +1,233 @@
+"""``archie skills …`` — generic skill catalogue + invoke.
+
+Extends the CLI beyond the 9 workstream-specific commands to the full
+public skill catalogue (51 skills at the time of writing). Mirrors the
+SDK shape: ``client.skills.list()`` + ``client.skills.invoke(slug, ...)``.
+
+* ``archie skills list [--category X] [--search Q]`` — table of every
+  visible skill, with category + cluster + streaming flag.
+* ``archie skills invoke <slug> [--input @file.json | --input '{json}']``
+  — POST the input to ``/api/v1/skills/{slug}/invoke`` and render the
+  unwrapped response.
+
+Auth + ``--json`` + ``--profile`` flags share the same decorator as the
+workstream commands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json as jsonlib
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+import httpx
+from rich.console import Console
+from rich.json import JSON
+from rich.table import Table
+
+from archie_cli.auth import CredentialError, load_credentials
+from archie_cli.client import ArchieAPIError, ArchieClient
+
+_console = Console()
+_err_console = Console(stderr=True, style="bold red")
+
+
+def _global_options(fn):
+    """Auth + output flags — same shape as workstreams.py to keep UX uniform."""
+    fn = click.option(
+        "--json",
+        "as_json",
+        is_flag=True,
+        default=False,
+        help="Emit raw JSON to stdout (machine-friendly).",
+    )(fn)
+    fn = click.option(
+        "--profile",
+        default=None,
+        help="Credentials profile in ~/.archie/credentials.toml (default: 'default').",
+    )(fn)
+    fn = click.option(
+        "--api-url",
+        default=None,
+        envvar="ARCHIE_API_URL",
+        help="API base URL. Falls back to env ARCHIE_API_URL or saved credentials.",
+    )(fn)
+    fn = click.option(
+        "--api-key",
+        default=None,
+        envvar="ARCHIE_API_KEY",
+        help="Bearer token. Falls back to env ARCHIE_API_KEY or saved credentials.",
+    )(fn)
+    return fn
+
+
+def _resolve_creds(api_url: str | None, api_key: str | None, profile: str | None):
+    try:
+        return load_credentials(
+            profile=profile or "default",
+            api_url_override=api_url,
+            api_key_override=api_key,
+        )
+    except CredentialError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _run(coro):
+    try:
+        return asyncio.run(coro)
+    except ArchieAPIError as exc:
+        _err_console.print(str(exc))
+        raise click.exceptions.Exit(2) from exc
+    except KeyboardInterrupt:
+        _err_console.print("\nInterrupted.")
+        raise click.exceptions.Exit(130) from None
+
+
+@click.group("skills")
+def skills_group() -> None:
+    """Browse and invoke the Archie skill catalogue."""
+
+
+@skills_group.command("list")
+@_global_options
+@click.option("--category", default=None, help="Filter by category (e.g. transactions, tax).")
+@click.option(
+    "--search",
+    "search",
+    default=None,
+    help="Case-insensitive substring match on slug or description.",
+)
+def list_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    category: str | None,
+    search: str | None,
+) -> None:
+    """List the skill catalogue visible to the caller."""
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go() -> list[dict[str, Any]]:
+        # The catalogue lives at /api/v1/skills (GET) — separate from the
+        # /api/v1/skills/{slug}/invoke surface. We hit it directly to avoid
+        # adding a bespoke client method just for the CLI.
+        async with httpx.AsyncClient(
+            base_url=creds.api_url,
+            headers={"Authorization": f"Bearer {creds.api_key}"},
+            timeout=15.0,
+        ) as cli:
+            resp = await cli.get("/api/v1/skills")
+            if resp.status_code >= 400:
+                raise ArchieAPIError(
+                    resp.status_code,
+                    resp.json()
+                    if resp.headers.get("content-type", "").startswith("application/json")
+                    else resp.text,
+                )
+            body = resp.json()
+        return body.get("data") if isinstance(body, dict) else body
+
+    skills = _run(go()) or []
+    if category:
+        skills = [s for s in skills if s.get("category") == category]
+    if search:
+        needle = search.lower()
+        skills = [
+            s
+            for s in skills
+            if needle in (s.get("slug", "") + " " + s.get("description", "")).lower()
+        ]
+
+    if as_json:
+        sys.stdout.write(jsonlib.dumps(skills, indent=2, default=str))
+        sys.stdout.write("\n")
+        return
+
+    if not skills:
+        _console.print("[dim]No skills match.[/dim]")
+        return
+
+    table = Table(title=f"{len(skills)} skill(s)")
+    table.add_column("Slug", style="cyan")
+    table.add_column("Category", style="magenta")
+    table.add_column("Streams")
+    table.add_column("Description")
+    for s in sorted(skills, key=lambda x: x.get("slug", "")):
+        table.add_row(
+            s.get("slug", ""),
+            s.get("category", ""),
+            "yes" if s.get("streaming") else "no",
+            (s.get("description") or "")[:80],
+        )
+    _console.print(table)
+
+
+@skills_group.command("invoke")
+@_global_options
+@click.argument("slug")
+@click.option(
+    "--input",
+    "input_",
+    default="{}",
+    show_default=True,
+    help=(
+        "Skill input as inline JSON (e.g. '--input \\'{\"query\":\"...\"}\\'') "
+        "or a file path prefixed with @ (e.g. '--input @body.json'). "
+        "Default is empty object."
+    ),
+)
+def invoke_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    slug: str,
+    input_: str,
+) -> None:
+    """Invoke a skill by its public slug (e.g. ``ask_archie``, ``tax.advise``).
+
+    The slug accepts both the friendly name (``tax.advise``) and the
+    internal slug (``advise_tax``). The route translates either to
+    ``/api/v1/skills/{slug}/invoke`` server-side.
+    """
+    payload = _parse_input(input_)
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go() -> dict[str, Any]:
+        async with ArchieClient(creds) as cli:
+            return await cli.invoke_skill(slug, payload)
+
+    out = _run(go())
+    if as_json:
+        sys.stdout.write(jsonlib.dumps(out, indent=2, default=str))
+        sys.stdout.write("\n")
+    else:
+        _console.print(JSON.from_data(out))
+
+
+def _parse_input(value: str) -> dict[str, Any]:
+    """``--input`` accepts inline JSON, ``@path``, or ``-`` for stdin."""
+    text = value
+    if value.startswith("@"):
+        path = Path(value[1:])
+        if not path.exists():
+            raise click.BadParameter(f"input file not found: {path}", param_hint="--input")
+        text = path.read_text()
+    elif value == "-":
+        text = sys.stdin.read()
+    try:
+        parsed = jsonlib.loads(text)
+    except jsonlib.JSONDecodeError as exc:
+        raise click.BadParameter(
+            f"--input is not valid JSON: {exc.msg} (at line {exc.lineno} col {exc.colno})",
+            param_hint="--input",
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise click.BadParameter(
+            "--input must be a JSON object (got non-object)", param_hint="--input"
+        )
+    return parsed

archie_cli/cmds/workstreams.py

@@ -0,0 +1,298 @@
+"""``archie workstreams …`` — list, describe, run, status, cancel, logs."""
+
+from __future__ import annotations
+
+import asyncio
+import json as jsonlib
+import sys
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.json import JSON
+from rich.table import Table
+
+from archie_cli.auth import CredentialError, load_credentials
+from archie_cli.client import ArchieAPIError, ArchieClient
+
+_console = Console()
+_err_console = Console(stderr=True, style="bold red")
+
+
+def _global_options(fn):
+    """Attach the auth + output flags every workstream command needs."""
+    fn = click.option(
+        "--json",
+        "as_json",
+        is_flag=True,
+        default=False,
+        help="Emit raw JSON to stdout (machine-friendly).",
+    )(fn)
+    fn = click.option(
+        "--profile",
+        default=None,
+        help="Credentials profile in ~/.archie/credentials.toml (default: 'default').",
+    )(fn)
+    fn = click.option(
+        "--api-url",
+        default=None,
+        envvar="ARCHIE_API_URL",
+        help="API base URL. Falls back to env ARCHIE_API_URL or saved credentials.",
+    )(fn)
+    fn = click.option(
+        "--api-key",
+        default=None,
+        envvar="ARCHIE_API_KEY",
+        help="Bearer token. Falls back to env ARCHIE_API_KEY or saved credentials.",
+    )(fn)
+    return fn
+
+
+def _resolve_creds(api_url: str | None, api_key: str | None, profile: str | None):
+    try:
+        return load_credentials(
+            profile=profile or "default",
+            api_url_override=api_url,
+            api_key_override=api_key,
+        )
+    except CredentialError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _emit(payload: Any, *, as_json: bool) -> None:
+    if as_json:
+        sys.stdout.write(jsonlib.dumps(payload, indent=2, default=str))
+        sys.stdout.write("\n")
+    else:
+        _console.print(JSON.from_data(payload))
+
+
+def _run(coro):
+    """Bridge sync click handlers to async client calls."""
+    try:
+        return asyncio.run(coro)
+    except ArchieAPIError as exc:
+        _err_console.print(str(exc))
+        raise click.exceptions.Exit(2) from exc
+    except KeyboardInterrupt:
+        _err_console.print("\nInterrupted.")
+        raise click.exceptions.Exit(130) from None
+
+
+@click.group("workstreams")
+def workstreams_group() -> None:
+    """Operate on Archie workstreams (templates, blueprints, cycles, tasks)."""
+
+
+@workstreams_group.command("list")
+@_global_options
+@click.option("--scope", type=click.Choice(["plan", "user", "team", "firm", "gallery"]))
+@click.option("--status", type=click.Choice(["draft", "active", "archived"]))
+@click.option("--limit", type=click.IntRange(1, 100), default=20, show_default=True)
+@click.option("--cursor", default=None, help="Opaque pagination cursor from a previous response.")
+def list_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    scope: str | None,
+    status: str | None,
+    limit: int,
+    cursor: str | None,
+) -> None:
+    """List workstreams visible to the caller."""
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            return await cli.workstreams_list(
+                scope=scope,
+                status=status,
+                limit=limit,
+                cursor=cursor,
+            )
+
+    out = _run(go())
+    if as_json:
+        _emit(out, as_json=True)
+        return
+    items = out.get("items") or []
+    if not items:
+        _console.print("[dim]No workstreams visible.[/dim]")
+        return
+    table = Table(title=f"{len(items)} workstream(s)")
+    table.add_column("Permakey", style="cyan")
+    table.add_column("Name")
+    table.add_column("Mode", style="magenta")
+    table.add_column("Status")
+    for w in items:
+        table.add_row(
+            w.get("permakey", ""),
+            w.get("name", ""),
+            w.get("execution_mode", ""),
+            w.get("status", ""),
+        )
+    _console.print(table)
+    next_cursor = out.get("next_cursor")
+    if next_cursor:
+        _console.print(f"\n[dim]More results: --cursor {next_cursor}[/dim]")
+
+
+@workstreams_group.command("describe")
+@_global_options
+@click.argument("workstream_id")
+def describe_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    workstream_id: str,
+) -> None:
+    """Describe a workstream (UUID, slug, or 7-char permakey)."""
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            return await cli.workstreams_describe(workstream_id)
+
+    out = _run(go())
+    _emit(out, as_json=as_json)
+
+
+@workstreams_group.command("run")
+@_global_options
+@click.argument("workstream_id")
+@click.option("--client-id", default=None, help="Client UUID to run against.")
+@click.option("--period", default=None, help="Period label (e.g. FY26-Q1).")
+@click.option(
+    "--var",
+    "vars_",
+    multiple=True,
+    metavar="K=V",
+    help="Runtime variable. May be repeated. Use JSON for non-string values: --var qty='[1,2]'.",
+)
+@click.option(
+    "--idempotency-key",
+    default=None,
+    help="Caller-supplied stable token; safe-retry within 24h.",
+)
+def run_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    workstream_id: str,
+    client_id: str | None,
+    period: str | None,
+    vars_: tuple[str, ...],
+    idempotency_key: str | None,
+) -> None:
+    """Start a workstream cycle and print the cycle id + URLs."""
+    runtime_vars: dict[str, Any] = {}
+    for v in vars_:
+        if "=" not in v:
+            raise click.BadParameter(f"--var must be K=V (got {v!r})")
+        key, _, val = v.partition("=")
+        try:
+            runtime_vars[key] = jsonlib.loads(val)
+        except jsonlib.JSONDecodeError:
+            runtime_vars[key] = val
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            return await cli.workstreams_run(
+                workstream_id,
+                client_id=client_id,
+                period=period,
+                runtime_vars=runtime_vars or None,
+                idempotency_key=idempotency_key,
+            )
+
+    out = _run(go())
+    _emit(out, as_json=as_json)
+
+
+@workstreams_group.command("status")
+@_global_options
+@click.argument("cycle_id")
+def status_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    cycle_id: str,
+) -> None:
+    """Show the current state of a cycle."""
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            return await cli.workstreams_status(cycle_id)
+
+    out = _run(go())
+    _emit(out, as_json=as_json)
+
+
+@workstreams_group.command("cancel")
+@_global_options
+@click.argument("cycle_id")
+@click.option("--reason", default=None, help="Audit-trail reason (recommended).")
+@click.option("--idempotency-key", default=None, help="Caller-supplied stable token.")
+def cancel_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    cycle_id: str,
+    reason: str | None,
+    idempotency_key: str | None,
+) -> None:
+    """Cancel a running cycle."""
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            return await cli.workstreams_cancel(
+                cycle_id,
+                reason=reason,
+                idempotency_key=idempotency_key,
+            )
+
+    out = _run(go())
+    _emit(out, as_json=as_json)
+
+
+@workstreams_group.command("logs")
+@_global_options
+@click.argument("cycle_id")
+@click.option("--follow/--no-follow", "follow", default=True, show_default=True)
+def logs_cmd(
+    api_key: str | None,
+    api_url: str | None,
+    profile: str | None,
+    as_json: bool,
+    cycle_id: str,
+    follow: bool,
+) -> None:
+    """Stream cycle events via SSE.
+
+    Default is `--follow` (long-lived); use `--no-follow` to read whatever is
+    buffered and exit.
+    """
+    creds = _resolve_creds(api_url, api_key, profile)
+
+    async def go():
+        async with ArchieClient(creds) as cli:
+            async for event in cli.workstreams_events(cycle_id):
+                if as_json:
+                    sys.stdout.write(jsonlib.dumps(event, default=str) + "\n")
+                    sys.stdout.flush()
+                else:
+                    _console.print(JSON.from_data(event))
+                if not follow:
+                    # Snapshot mode — exit after the first batch lull.
+                    if event.get("kind") in {"finalization", "completed", "failed", "cancelled"}:
+                        break
+
+    _run(go())

heyarchie_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: heyarchie-cli
+Version: 0.1.0
+Summary: Command-line interface for the Archie Connect platform — workstreams, cycles, skills.
+Project-URL: Homepage, https://developers.heyarchie.ai
+Project-URL: Documentation, https://developers.heyarchie.ai/docs/cli
+Project-URL: Source, https://github.com/heyarchie-ai/archie-platform-v2/tree/alpha/apps/cli
+Author-email: Archie <hey@archie.ai>
+License: Proprietary
+Keywords: archie,cli,connect,workstreams
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.11
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: rich<14.0,>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# archie CLI
+
+Command-line interface for the Archie Connect platform.
+
+## Install
+
+```bash
+# from PyPI (when published)
+pipx install heyarchie-cli
+
+# or from this repo for development
+pip install -e apps/cli
+```
+
+`pipx` is recommended; it installs `archie` as a self-contained executable on
+your PATH without touching system Python packages.
+
+## Authenticate
+
+```bash
+archie login --api-url https://api.heyarchie.ai
+# Then paste your bearer token at the prompt (input is hidden).
+```
+
+This writes `~/.archie/credentials.toml` (chmod 600) under the `[default]`
+profile. Override per-call with `--profile`, `--api-key`, or env vars
+`ARCHIE_API_KEY` / `ARCHIE_API_URL`.
+
+> Today the bearer must be an **Archie session JWT** or **Archie OAuth JWT**.
+> WorkOS-issued `sk_*` API keys are not yet validated server-side — see
+> [`docs/connect/api-keys-flow.md`](../../docs/connect/api-keys-flow.md) for
+> the architectural decision pending.
+
+## Commands
+
+```text
+archie login                                 Save bearer credentials.
+archie workstreams list [--scope ...]        List visible workstreams.
+archie workstreams describe <id>             Show metadata + step graph.
+archie workstreams run <id> [--var k=v]      Start a cycle.
+archie workstreams status <cycle_id>         Show cycle progress.
+archie workstreams cancel <cycle_id>         Cancel a running cycle.
+archie workstreams logs <cycle_id>           Stream SSE events live.
+```
+
+`workstream_id` accepts a UUID, a workstream slug, or a 7-char permakey;
+the API resolves all three.
+
+## Examples
+
+```bash
+# List workstreams
+archie workstreams list
+
+# JSON output (pipe-friendly)
+archie workstreams list --json | jq '.items[].permakey'
+
+# Start a cycle and watch it run
+CYCLE=$(archie workstreams run abc1234 --period 2026-Q1 --json | jq -r .cycle_id)
+archie workstreams logs "$CYCLE"
+```
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `ARCHIE_API_URL` | API base URL | `https://api.heyarchie.ai` |
+| `ARCHIE_API_KEY` | Bearer token | (none) |
+
+CLI flags take precedence over env, which takes precedence over the
+on-disk credentials file.
+
+## Where this lives
+
+`apps/cli/` in the `archie-platform-v2` monorepo. PRs welcome.

heyarchie_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+archie_cli/__init__.py,sha256=-0B5hLpuva9c1HFjodsV1uRhOseWbFqpuwkNM6VD4tk,459
+archie_cli/__main__.py,sha256=GX-a-7hRx5xSAkTmZBErQ2w5XxGxDafNSAZzPzgitHk,804
+archie_cli/auth.py,sha256=5Z-1VOVLkJTNrKSdwEsyMTtyUhpx2juQvjsLYTrfUXM,3221
+archie_cli/client.py,sha256=pbPLq2DphIx1tq8b2CLX_K8y2spNxND-HIdcV4doVWo,6453
+archie_cli/cmds/__init__.py,sha256=bPwqo_P2WUBxzLSQyrijoLWpEZjLSF6MrnPyD91CCc4,52
+archie_cli/cmds/login.py,sha256=UHJbl0rl4caqktaHzy-QryPVHeqReL81B_0gzzV9hp0,1424
+archie_cli/cmds/skills.py,sha256=BH-VJ4j8eHwk1RUNdButZ_COX2WIDuPRWZdNSONOCp8,7299
+archie_cli/cmds/workstreams.py,sha256=ol87X60M69pJopL165FH-ahmy4ibfq3m1WiqBNa6pfY,8794
+heyarchie_cli-0.1.0.dist-info/METADATA,sha256=xLSVzTAlVHh-uRFWjs0M14reuiqFmgol70NFixE06c8,3284
+heyarchie_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+heyarchie_cli-0.1.0.dist-info/entry_points.txt,sha256=pL_BexbbOi-N7AtfHCfIQN00nDsgPTqV0iNruhChUzo,52
+heyarchie_cli-0.1.0.dist-info/RECORD,,

heyarchie_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

heyarchie_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+archie = archie_cli.__main__:main