spooling 0.2.13__tar.gz → 0.2.15__tar.gz

{spooling-0.2.13/spooling.egg-info → spooling-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.13
+Version: 0.2.15
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -415,6 +415,49 @@ spooling push --dry-run       # show what would be pushed
 
 `push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
 
+### Push only some sessions, or to a specific team
+
+**Which team gets the sessions** is decided by the API key you are logged in with. Each key belongs to one workspace (personal or a team), and `spooling push` sends to that workspace. Mint a key for the team in the app, then log in with it:
+
+```bash
+spooling cloud teams                         # every workspace (personal + teams) your account belongs to
+spooling cloud whoami                        # the account and workspace this CLI pushes to
+spooling cloud login --key sk_<team-key>     # replaces the stored key; later pushes go to this team
+```
+
+`spooling cloud teams` marks the workspace your current key pushes to with `<- this key`, and shows your role, the number of members and the plan for each. `spooling cloud status` also prints the workspace name now. `teams` and `whoami` take `--json` for scripting.
+
+To push to a different team, log in with that team's key. Only one key is stored at a time, so check `spooling cloud whoami` before a push if you work with several teams. These commands need a server that supports `/v1/me`; against an older one they say so and `spooling cloud status` still works.
+
+**Which sessions go up.** With no filters, `spooling push` sends the most recent `--limit` sessions from every project on the machine. Use these to send only some of them. Filters combine with AND:
+
+| Option | Matches |
+|---|---|
+| `--project NAME` | Sessions whose project name is exactly `NAME` (find names with `spooling cost breakdown --by project`) |
+| `--cwd TEXT` | Sessions whose working directory contains `TEXT` (case-insensitive) |
+| `--title TEXT` | Sessions whose title contains `TEXT` (case-insensitive). Useful when an agent was launched from your home directory, so every session shares a generic working directory, but the project name is in the title |
+
+```bash
+spooling cloud login --key sk_<team-key>
+spooling push --cwd toebox --dry-run     # preview what would be sent; nothing is uploaded
+spooling push --cwd toebox               # send only sessions from the toebox directory
+spooling push --project my-app --limit 200
+spooling push --title islet              # sessions with "islet" in the title
+```
+
+**Share the same sessions with more than one team.** Add `--copy` to write the sessions into the workspace you are logged into as fresh rows, even if they were already pushed to another workspace. Re-running is safe:
+
+```bash
+spooling cloud login --key sk_<other-team-key>
+spooling push --cwd toebox --copy
+```
+
+**Include trace data.** Add `--with-spans` to also push each session's trace and spans (per-LLM-call usage, cost, tool calls, MCP calls and agent runs). The Traces page in the app, its agent, tool and MCP filters, and `spooling agents --cloud` / `spooling mcps --cloud` all rely on it. `--with-spans` can't be combined with `--copy` yet.
+
+**Secrets** (cloud and AWS keys, GitHub, OpenAI, Anthropic and Stripe tokens, PEM private keys, and `KEY=VALUE` lines whose key looks sensitive) are redacted on your machine before anything is uploaded. Pass `--no-redact` only if you are sure the content is clean.
+
+`spooling cloud watch` has no filters: it keeps pushing every new or updated session to the workspace you are logged into. Use filtered `spooling push` runs when you need to keep some sessions out.
+
 To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)

{spooling-0.2.13 → spooling-0.2.15}/README.md

@@ -379,6 +379,49 @@ spooling push --dry-run       # show what would be pushed
 
 `push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
 
+### Push only some sessions, or to a specific team
+
+**Which team gets the sessions** is decided by the API key you are logged in with. Each key belongs to one workspace (personal or a team), and `spooling push` sends to that workspace. Mint a key for the team in the app, then log in with it:
+
+```bash
+spooling cloud teams                         # every workspace (personal + teams) your account belongs to
+spooling cloud whoami                        # the account and workspace this CLI pushes to
+spooling cloud login --key sk_<team-key>     # replaces the stored key; later pushes go to this team
+```
+
+`spooling cloud teams` marks the workspace your current key pushes to with `<- this key`, and shows your role, the number of members and the plan for each. `spooling cloud status` also prints the workspace name now. `teams` and `whoami` take `--json` for scripting.
+
+To push to a different team, log in with that team's key. Only one key is stored at a time, so check `spooling cloud whoami` before a push if you work with several teams. These commands need a server that supports `/v1/me`; against an older one they say so and `spooling cloud status` still works.
+
+**Which sessions go up.** With no filters, `spooling push` sends the most recent `--limit` sessions from every project on the machine. Use these to send only some of them. Filters combine with AND:
+
+| Option | Matches |
+|---|---|
+| `--project NAME` | Sessions whose project name is exactly `NAME` (find names with `spooling cost breakdown --by project`) |
+| `--cwd TEXT` | Sessions whose working directory contains `TEXT` (case-insensitive) |
+| `--title TEXT` | Sessions whose title contains `TEXT` (case-insensitive). Useful when an agent was launched from your home directory, so every session shares a generic working directory, but the project name is in the title |
+
+```bash
+spooling cloud login --key sk_<team-key>
+spooling push --cwd toebox --dry-run     # preview what would be sent; nothing is uploaded
+spooling push --cwd toebox               # send only sessions from the toebox directory
+spooling push --project my-app --limit 200
+spooling push --title islet              # sessions with "islet" in the title
+```
+
+**Share the same sessions with more than one team.** Add `--copy` to write the sessions into the workspace you are logged into as fresh rows, even if they were already pushed to another workspace. Re-running is safe:
+
+```bash
+spooling cloud login --key sk_<other-team-key>
+spooling push --cwd toebox --copy
+```
+
+**Include trace data.** Add `--with-spans` to also push each session's trace and spans (per-LLM-call usage, cost, tool calls, MCP calls and agent runs). The Traces page in the app, its agent, tool and MCP filters, and `spooling agents --cloud` / `spooling mcps --cloud` all rely on it. `--with-spans` can't be combined with `--copy` yet.
+
+**Secrets** (cloud and AWS keys, GitHub, OpenAI, Anthropic and Stripe tokens, PEM private keys, and `KEY=VALUE` lines whose key looks sensitive) are redacted on your machine before anything is uploaded. Pass `--no-redact` only if you are sure the content is clean.
+
+`spooling cloud watch` has no filters: it keeps pushing every new or updated session to the workspace you are logged into. Use filtered `spooling push` runs when you need to keep some sessions out.
+
 To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)

{spooling-0.2.13 → spooling-0.2.15}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.13"
+version = "0.2.15"
 description = "Local session tracker and semantic search for AI coding assistants"
 readme = "README.md"
 authors = [{ name = "Parsed Analytics, Inc." }]

{spooling-0.2.13 → spooling-0.2.15}/spooling/cloud.py

@@ -15,6 +15,7 @@ import click
 import httpx
 from rich.console import Console
 from rich.markup import escape
+from rich.table import Table
 
 from spooling.db import get_connection
 from spooling.redact import redact_messages, redact_traces
@@ -253,6 +254,10 @@ def cloud_status():
         r.raise_for_status()
         s = r.json()
         console.print(f"API: [cyan]{base}[/cyan]")
+        me = _fetch_me(required=False)
+        if me and me.get("workspace"):
+            ws = me["workspace"]
+            console.print(f"  workspace: [bold]{escape(ws['name'])}[/bold] [dim]({_kind_label(ws)})[/dim]")
         console.print(f"  sessions: [bold]{s.get('sessions', 0)}[/bold]")
         console.print(f"  messages: [bold]{s.get('messages', 0)}[/bold]")
         console.print(f"  providers: [bold]{s.get('providers', 0)}[/bold]")
@@ -263,6 +268,93 @@ def cloud_status():
         _fail(f"{_explain_error(e, base)}")
 
 
+def _fetch_me(*, required: bool) -> dict | None:
+    """GET /v1/me: who this key is and which workspaces its user belongs to.
+
+    ``required=False`` is for best-effort extras (returns None on any problem);
+    ``required=True`` explains failures and exits non-zero.
+    """
+    headers = _auth_headers()
+    base = _api_base()
+    try:
+        r = httpx.get(f"{base}/v1/me", headers=headers, timeout=15)
+        r.raise_for_status()
+        return r.json()
+    except httpx.HTTPStatusError as e:
+        if not required:
+            return None
+        if e.response.status_code == 404:
+            _fail(
+                "This server is older than the CLI and can't list workspaces yet.\n"
+                "  Ask your admin to redeploy it. Meanwhile `spooling cloud status`\n"
+                "  shows the totals of the workspace your key belongs to."
+            )
+        _fail(_explain_http(e))
+    except Exception as e:  # noqa: BLE001
+        if not required:
+            return None
+        _fail(_explain_error(e, base))
+
+
+def _kind_label(w: dict) -> str:
+    return "Personal" if w.get("kind") == "personal" else "Team"
+
+
+@cloud.command("whoami")
+@click.option("--json", "as_json", is_flag=True, help="Print JSON instead of text")
+def cloud_whoami(as_json: bool):
+    """Show which account and workspace (team) this CLI pushes to.
+
+    The workspace is decided by the API key you logged in with. Use
+    `spooling cloud teams` to see every workspace you belong to.
+    """
+    me = _fetch_me(required=True)
+    if as_json:
+        click.echo(json.dumps(me, indent=2))
+        return
+    user, ws = me["user"], me.get("workspace")
+    who = user.get("email") or user.get("name") or user.get("id")
+    console.print(f"Account:   [bold]{escape(str(who))}[/bold]")
+    if ws:
+        role = f", you are {ws['role']}" if ws.get("role") else ""
+        members = f", {ws['members']} member{'s' if ws['members'] != 1 else ''}" if ws.get("members") is not None else ""
+        console.print(f"Workspace: [bold cyan]{escape(ws['name'])}[/bold cyan] [dim]({_kind_label(ws)}{role}{members}, {ws.get('plan', 'free')} plan)[/dim]")
+    console.print(f"API:       [dim]{_api_base()}[/dim]")
+    console.print("[dim]`spooling push` sends sessions to this workspace. See all of yours with `spooling cloud teams`.[/dim]")
+
+
+@cloud.command("teams")
+@click.option("--json", "as_json", is_flag=True, help="Print JSON instead of a table")
+def cloud_teams(as_json: bool):
+    """List every workspace (personal + teams) your account belongs to.
+
+    The row marked ``<- this key`` is where `spooling push` sends sessions.
+    To push somewhere else, log in with that team's API key:
+    `spooling cloud login --key sk_<team-key>`.
+    """
+    me = _fetch_me(required=True)
+    if as_json:
+        click.echo(json.dumps(me["workspaces"], indent=2))
+        return
+    rows = me["workspaces"]
+    table = Table(title="Your workspaces", show_lines=False)
+    table.add_column("Workspace", style="cyan")
+    table.add_column("Type")
+    table.add_column("Your role")
+    table.add_column("Members", justify="right")
+    table.add_column("Plan", style="dim")
+    table.add_column("")
+    for w in rows:
+        table.add_row(
+            escape(w["name"]), _kind_label(w), w.get("role") or "-",
+            str(w["members"]) if w.get("members") is not None else "-",
+            w.get("plan", "free"),
+            "[green]<- this key[/green]" if w.get("current") else "",
+        )
+    console.print(table if rows else "[yellow]No workspaces found for this account.[/yellow]")
+    console.print("[dim]A key pushes to one workspace. Switch with `spooling cloud login --key sk_<that team's key>`.[/dim]")
+
+
 @cloud.command("logout")
 def cloud_logout():
     """Remove the stored API key."""
@@ -627,7 +719,7 @@ _SYNC_OPTION = click.option(
 @click.option(
     "--project",
     default=None,
-    help="Only push sessions whose project name matches exactly. Pair with `spooling stats --by project` to discover names.",
+    help="Only push sessions whose project name matches exactly. Pair with `spooling cost breakdown --by project` to discover names.",
 )
 @click.option(
     "--cwd",

{spooling-0.2.13 → spooling-0.2.15/spooling.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.13
+Version: 0.2.15
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -415,6 +415,49 @@ spooling push --dry-run       # show what would be pushed
 
 `push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
 
+### Push only some sessions, or to a specific team
+
+**Which team gets the sessions** is decided by the API key you are logged in with. Each key belongs to one workspace (personal or a team), and `spooling push` sends to that workspace. Mint a key for the team in the app, then log in with it:
+
+```bash
+spooling cloud teams                         # every workspace (personal + teams) your account belongs to
+spooling cloud whoami                        # the account and workspace this CLI pushes to
+spooling cloud login --key sk_<team-key>     # replaces the stored key; later pushes go to this team
+```
+
+`spooling cloud teams` marks the workspace your current key pushes to with `<- this key`, and shows your role, the number of members and the plan for each. `spooling cloud status` also prints the workspace name now. `teams` and `whoami` take `--json` for scripting.
+
+To push to a different team, log in with that team's key. Only one key is stored at a time, so check `spooling cloud whoami` before a push if you work with several teams. These commands need a server that supports `/v1/me`; against an older one they say so and `spooling cloud status` still works.
+
+**Which sessions go up.** With no filters, `spooling push` sends the most recent `--limit` sessions from every project on the machine. Use these to send only some of them. Filters combine with AND:
+
+| Option | Matches |
+|---|---|
+| `--project NAME` | Sessions whose project name is exactly `NAME` (find names with `spooling cost breakdown --by project`) |
+| `--cwd TEXT` | Sessions whose working directory contains `TEXT` (case-insensitive) |
+| `--title TEXT` | Sessions whose title contains `TEXT` (case-insensitive). Useful when an agent was launched from your home directory, so every session shares a generic working directory, but the project name is in the title |
+
+```bash
+spooling cloud login --key sk_<team-key>
+spooling push --cwd toebox --dry-run     # preview what would be sent; nothing is uploaded
+spooling push --cwd toebox               # send only sessions from the toebox directory
+spooling push --project my-app --limit 200
+spooling push --title islet              # sessions with "islet" in the title
+```
+
+**Share the same sessions with more than one team.** Add `--copy` to write the sessions into the workspace you are logged into as fresh rows, even if they were already pushed to another workspace. Re-running is safe:
+
+```bash
+spooling cloud login --key sk_<other-team-key>
+spooling push --cwd toebox --copy
+```
+
+**Include trace data.** Add `--with-spans` to also push each session's trace and spans (per-LLM-call usage, cost, tool calls, MCP calls and agent runs). The Traces page in the app, its agent, tool and MCP filters, and `spooling agents --cloud` / `spooling mcps --cloud` all rely on it. `--with-spans` can't be combined with `--copy` yet.
+
+**Secrets** (cloud and AWS keys, GitHub, OpenAI, Anthropic and Stripe tokens, PEM private keys, and `KEY=VALUE` lines whose key looks sensitive) are redacted on your machine before anything is uploaded. Pass `--no-redact` only if you are sure the content is clean.
+
+`spooling cloud watch` has no filters: it keeps pushing every new or updated session to the workspace you are logged into. Use filtered `spooling push` runs when you need to keep some sessions out.
+
 To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)

{spooling-0.2.13 → spooling-0.2.15}/spooling.egg-info/SOURCES.txt

@@ -67,6 +67,8 @@ spooling/providers/windsurf.py
 tests/test_agent_spans.py
 tests/test_claude_code_provider.py
 tests/test_cloud_errors.py
+tests/test_cloud_teams.py
+tests/test_docs.py
 tests/test_insights.py
 tests/test_mcp_auth_middleware.py
 tests/test_session_ids.py

spooling-0.2.15/tests/test_cloud_teams.py

@@ -0,0 +1,118 @@
+"""`spooling cloud whoami` / `cloud teams` (GET /v1/me), and the workspace line in `cloud status`."""
+
+import json
+
+import httpx
+import pytest
+from click.testing import CliRunner
+
+from spooling import cloud
+from spooling.cli import cli
+
+ME = {
+    "user": {"id": "u1", "email": "dev@example.com", "name": "Dev"},
+    "workspace": {"id": "w1", "name": "Dev", "kind": "personal", "plan": "free", "role": "owner",
+                  "members": 1, "current": True},
+    "workspaces": [
+        {"id": "w1", "name": "Dev", "kind": "personal", "plan": "free", "role": "owner", "members": 1, "current": True},
+        {"id": "w2", "name": "Toebox", "kind": "team", "plan": "team", "role": "admin", "members": 4, "current": False},
+        {"id": "w3", "name": "[red]Odd[/red] Name", "kind": "team", "plan": "free", "role": "member", "members": 2, "current": False},
+    ],
+}
+STATS = {"sessions": 12, "messages": 340, "providers": 2, "cost": 1.5}
+
+
+def run(*args):
+    return CliRunner().invoke(cli, ["cloud", *args])
+
+
+@pytest.fixture
+def server(monkeypatch):
+    """Fake Spooling Cloud: path -> (status, json). Records the paths requested."""
+    routes = {"/v1/me": (200, ME), "/v1/stats": (200, STATS)}
+    seen = []
+    monkeypatch.setattr(cloud, "_auth_headers", lambda: {"Authorization": "Bearer sk_test"})
+    monkeypatch.setattr(cloud, "_api_base", lambda: "https://api.example")
+    monkeypatch.setattr(cloud, "_load_config", lambda: {"api_key": "sk_test"})
+
+    def fake_get(url, headers=None, params=None, timeout=None):
+        path = url.replace("https://api.example", "")
+        seen.append(path)
+        status, body = routes[path]
+        return httpx.Response(status, json=body, request=httpx.Request("GET", url))
+
+    monkeypatch.setattr(cloud.httpx, "get", fake_get)
+    return type("S", (), {"routes": routes, "seen": seen})
+
+
+def test_whoami_shows_account_workspace_and_role(server):
+    r = run("whoami")
+    assert r.exit_code == 0
+    assert "dev@example.com" in r.output and "Dev" in r.output
+    assert "Personal" in r.output and "owner" in r.output and "1 member," in r.output
+    assert "spooling push" in r.output
+
+
+def test_whoami_json(server):
+    assert json.loads(run("whoami", "--json").output) == ME
+
+
+def test_teams_lists_all_workspaces_and_marks_the_current_one(server):
+    r = run("teams")
+    assert r.exit_code == 0
+    for name in ("Toebox", "Personal", "Team", "admin", "member"):
+        assert name in r.output
+    current_rows = [l for l in r.output.splitlines() if "<- this key" in l]
+    assert len(current_rows) == 1 and "Dev" in current_rows[0]
+
+
+def test_teams_does_not_interpret_markup_in_names(server):
+    assert "[red]Odd[/red] Name" in run("teams").output
+
+
+def test_teams_json_is_the_workspace_list(server):
+    data = json.loads(run("teams", "--json").output)
+    assert [w["name"] for w in data] == ["Dev", "Toebox", "[red]Odd[/red] Name"]
+    assert [w["current"] for w in data] == [True, False, False]
+
+
+def test_older_server_without_v1_me_explains_and_exits_nonzero(server):
+    server.routes["/v1/me"] = (404, {"detail": "Not Found"})
+    for cmd in ("whoami", "teams"):
+        r = run(cmd)
+        assert r.exit_code == 1
+        assert "older than the CLI" in r.output and "cloud status" in r.output
+
+
+def test_rejected_key_is_explained(server):
+    server.routes["/v1/me"] = (401, {"detail": "invalid or revoked key"})
+    r = run("whoami")
+    assert r.exit_code == 1 and "401" in r.output and "cloud login" in r.output
+
+
+def test_unreachable_server_exits_nonzero(server, monkeypatch):
+    def boom(*a, **k):
+        raise httpx.ConnectError("connection refused")
+    monkeypatch.setattr(cloud.httpx, "get", boom)
+    r = run("teams")
+    assert r.exit_code == 1 and "log in" not in r.output.lower()
+
+
+def test_status_shows_workspace_name_when_server_supports_it(server):
+    r = run("status")
+    assert r.exit_code == 0
+    assert "workspace" in r.output and "Dev" in r.output and "sessions" in r.output
+    assert "/v1/me" in server.seen
+
+
+def test_status_still_works_against_an_older_server(server):
+    server.routes["/v1/me"] = (404, {"detail": "Not Found"})
+    r = run("status")
+    assert r.exit_code == 0
+    assert "sessions" in r.output and "workspace:" not in r.output
+
+
+def test_status_ignores_a_failing_v1_me(server, monkeypatch):
+    server.routes["/v1/me"] = (500, {"detail": "boom"})
+    r = run("status")
+    assert r.exit_code == 0 and "sessions" in r.output

spooling-0.2.15/tests/test_docs.py

@@ -0,0 +1,40 @@
+"""Docs/help text must only point at options that exist."""
+
+from click.testing import CliRunner
+
+from spooling.cli import cli
+
+
+def _help(*args):
+    return CliRunner().invoke(cli, [*args, "--help"]).output
+
+
+def test_push_help_points_at_a_real_command_for_project_names():
+    out = _help("push")
+    assert "stats --by" not in out
+    assert "cost breakdown --by project" in out
+    # and that command really has the option the help names
+    assert "--by" in _help("cost", "breakdown")
+
+
+def test_push_documents_scoping_and_team_options():
+    out = _help("push")
+    for opt in ("--project", "--cwd", "--title", "--copy", "--with-spans", "--dry-run", "--no-redact"):
+        assert opt in out
+
+
+def test_readme_documents_every_push_scoping_option():
+    from pathlib import Path
+    readme = (Path(__file__).resolve().parent.parent / "README.md").read_text()
+    for opt in ("--project", "--cwd", "--title", "--copy", "--with-spans", "--dry-run", "--no-redact", "cloud login --key sk_<team-key>"):
+        assert opt in readme, f"README does not mention {opt}"
+    assert "stats --by" not in readme
+
+
+def test_readme_documents_the_team_commands():
+    from pathlib import Path
+    readme = (Path(__file__).resolve().parent.parent / "README.md").read_text()
+    for cmd in ("spooling cloud teams", "spooling cloud whoami"):
+        assert cmd in readme
+    out = CliRunner().invoke(cli, ["cloud", "--help"]).output
+    assert "teams" in out and "whoami" in out