albus-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{albus_cli-0.5.0 → albus_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: albus-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: Command-line client for the Albus REST API
 Project-URL: Homepage, https://github.com/albusgroup/albus-cli
 Project-URL: Repository, https://github.com/albusgroup/albus-cli
@@ -9,7 +9,7 @@ Author: Albus
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: albus-sdk==0.11.0
+Requires-Dist: albus-sdk==0.14.0
 Requires-Dist: typer<0.28,>=0.26.8
 Description-Content-Type: text/markdown
 
@@ -78,7 +78,11 @@ export ALBUS_BASE_URL=http://localhost:8080/api  # optional; defaults to prod
 ```
 
 `--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
-(a waiting `sessions run` long-polls and is exempt).
+(a waiting `sessions run` long-polls and is exempt). A user who belongs to
+several organizations acts in the one joined first; `--org <organization id>`
+(or `ALBUS_ORG`) selects another, and `albus whoami` lists them under
+`organizations` with the selected one as `active_organization`. An API key is
+bound to its organization and ignores `--org`.
 
 `albus login` opens a browser on this machine and listens on
 `127.0.0.1:8484-8487`; on a headless host, forward those ports or export
@@ -115,8 +119,12 @@ albus sessions run my-session -p "and the follow-up?" \
 albus sessions list
 albus sessions get my-session --limit 20
 albus sessions audit my-session --after "$cursor"
+albus sessions cancel my-session
 albus sessions delete my-session
 
+albus traces list --agent-name support-triage --status FAILED
+albus traces get "$invocation_key" --no-payloads --attempts all
+
 albus secrets list
 albus secrets create gemini-key --value ...   # or pipe the value on stdin
 albus secrets get gemini-key
@@ -132,11 +140,32 @@ albus tokens create ci
 albus tokens get "$id"
 albus tokens delete "$id"
 
+albus invites list
 albus invites create teammate@example.com
+albus invites revoke "$id"
+
+albus organization get
+albus organization rename "Albus Labs"
+albus organization members
+albus organization set-role "$user_id" admin
+albus organization remove-member "$user_id"
+
+albus billing balance
+albus billing ledger --after "$cursor"
+albus billing checkout 20 --success-url https://... --cancel-url https://...
 
 albus models list
+
+albus memories groups
+albus memories list --group team-a
+albus memories delete "$id" --group team-a
+albus memories delete-group --group team-a
 ```
 
+`memories groups` lists the organization's memory groups with their active
+counts; `memories list --group` reads one group's memories, newest first. Both
+page with `--after` and `--limit`.
+
 `models list` gives the model names `sessions run --model` takes, each with
 the provider it runs on — which is the provider the `--credential` secret has
 to be for.
@@ -144,9 +173,19 @@ to be for.
 `tokens create` prints the only copy of the key value the API ever returns;
 `list` and `get` return metadata alone.
 
-`invites create` invites a person by email, and they get their own
-organization on first sign-in. `CreateInviteRequest`'s `role` and
-`organization_id` have no flags: one user is one organization for the beta.
+`invites create` invites a person by email to join your active organization,
+as a `member` unless `--role admin` says otherwise. `invites list` and
+`invites revoke`, like the `organization` member commands, need the admin
+role.
+
+`billing checkout` starts a credit purchase and prints the payment page URL
+to send the buyer to; like `tokens` and `invites`, it needs `albus login`
+rather than an API key. `billing balance` and `billing ledger` take either.
+
+`traces list` searches the last 31 days of invocations unless `--since` and
+`--until` say otherwise; `traces get` reads one with a page of its spans, and
+`--no-payloads` returns the shape without what each span was given and
+produced.
 
 `sessions run` waits for the assistant response by default; pass `--no-wait`
 to return as soon as the invocation is accepted, or `--wait-timeout` to bound

{albus_cli-0.5.0 → albus_cli-0.7.0}/README.md

@@ -63,7 +63,11 @@ export ALBUS_BASE_URL=http://localhost:8080/api  # optional; defaults to prod
 ```
 
 `--base-url` overrides `ALBUS_BASE_URL`, and `--timeout` bounds each request
-(a waiting `sessions run` long-polls and is exempt).
+(a waiting `sessions run` long-polls and is exempt). A user who belongs to
+several organizations acts in the one joined first; `--org <organization id>`
+(or `ALBUS_ORG`) selects another, and `albus whoami` lists them under
+`organizations` with the selected one as `active_organization`. An API key is
+bound to its organization and ignores `--org`.
 
 `albus login` opens a browser on this machine and listens on
 `127.0.0.1:8484-8487`; on a headless host, forward those ports or export
@@ -100,8 +104,12 @@ albus sessions run my-session -p "and the follow-up?" \
 albus sessions list
 albus sessions get my-session --limit 20
 albus sessions audit my-session --after "$cursor"
+albus sessions cancel my-session
 albus sessions delete my-session
 
+albus traces list --agent-name support-triage --status FAILED
+albus traces get "$invocation_key" --no-payloads --attempts all
+
 albus secrets list
 albus secrets create gemini-key --value ...   # or pipe the value on stdin
 albus secrets get gemini-key
@@ -117,11 +125,32 @@ albus tokens create ci
 albus tokens get "$id"
 albus tokens delete "$id"
 
+albus invites list
 albus invites create teammate@example.com
+albus invites revoke "$id"
+
+albus organization get
+albus organization rename "Albus Labs"
+albus organization members
+albus organization set-role "$user_id" admin
+albus organization remove-member "$user_id"
+
+albus billing balance
+albus billing ledger --after "$cursor"
+albus billing checkout 20 --success-url https://... --cancel-url https://...
 
 albus models list
+
+albus memories groups
+albus memories list --group team-a
+albus memories delete "$id" --group team-a
+albus memories delete-group --group team-a
 ```
 
+`memories groups` lists the organization's memory groups with their active
+counts; `memories list --group` reads one group's memories, newest first. Both
+page with `--after` and `--limit`.
+
 `models list` gives the model names `sessions run --model` takes, each with
 the provider it runs on — which is the provider the `--credential` secret has
 to be for.
@@ -129,9 +158,19 @@ to be for.
 `tokens create` prints the only copy of the key value the API ever returns;
 `list` and `get` return metadata alone.
 
-`invites create` invites a person by email, and they get their own
-organization on first sign-in. `CreateInviteRequest`'s `role` and
-`organization_id` have no flags: one user is one organization for the beta.
+`invites create` invites a person by email to join your active organization,
+as a `member` unless `--role admin` says otherwise. `invites list` and
+`invites revoke`, like the `organization` member commands, need the admin
+role.
+
+`billing checkout` starts a credit purchase and prints the payment page URL
+to send the buyer to; like `tokens` and `invites`, it needs `albus login`
+rather than an API key. `billing balance` and `billing ledger` take either.
+
+`traces list` searches the last 31 days of invocations unless `--since` and
+`--until` say otherwise; `traces get` reads one with a page of its spans, and
+`--no-payloads` returns the shape without what each span was given and
+produced.
 
 `sessions run` waits for the assistant response by default; pass `--no-wait`
 to return as soon as the invocation is accepted, or `--wait-timeout` to bound

{albus_cli-0.5.0 → albus_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "albus-cli"
-version = "0.5.0"
+version = "0.7.0"
 description = "Command-line client for the Albus REST API"
 readme = "README.md"
 license = "MIT"
@@ -13,7 +13,7 @@ authors = [{ name = "Albus" }]
 dependencies = [
     # Pinned, not floated: the published CLI states the one SDK version it was
     # tested against, and bumping it is a reviewed edit made when releasing.
-    "albus-sdk==0.11.0",
+    "albus-sdk==0.14.0",
     "typer>=0.26.8,<0.28",
 ]
 

{albus_cli-0.5.0 → albus_cli-0.7.0}/src/albus_cli/client.py

@@ -18,6 +18,11 @@ from albus_cli.credentials import Credential
 
 API_KEY_ENV = "ALBUS_API_KEY"
 BASE_URL_ENV = "ALBUS_BASE_URL"
+ORGANIZATION_ENV = "ALBUS_ORG"
+
+# Selects among the signed-in user's organizations. An API key is bound to
+# one already, and the server ignores the header for it.
+ORGANIZATION_HEADER = "X-Albus-Organization"
 
 # Renew slightly early: an access token that outlives the request it is
 # sent on is not worth the 401.
@@ -53,22 +58,29 @@ def api_key() -> str | None:
     return os.environ.get(API_KEY_ENV)
 
 
-def client(base_url: str, timeout: float | None) -> Albus:
-    """Build an SDK client. A timeout of None disables the read timeout."""
+def client(
+    base_url: str, timeout: float | None, organization: str | None
+) -> Albus:
+    """Build an SDK client. A timeout of None disables the read timeout;
+    an organization selects which of the user's the requests act in."""
     key = api_key()
     if key:
         # The environment wins over a stored session deliberately, so CI
         # and agent harnesses inject a credential without touching disk.
-        return _client(base_url, timeout, api_key=key)
+        return _client(base_url, timeout, organization, api_key=key)
 
     stored = credentials.load(base_url)
     if stored is None:
         raise _signed_out(base_url)
 
-    return bearer_client(base_url, timeout, _current(base_url, stored))
+    return bearer_client(
+        base_url, timeout, organization, _current(base_url, stored)
+    )
 
 
-def signed_in_client(base_url: str, timeout: float | None) -> Albus:
+def signed_in_client(
+    base_url: str, timeout: float | None, organization: str | None
+) -> Albus:
     """A client on the browser session. The operations Albus accepts
     only a human bearer token for use it directly: an API key is a 401
     there, and the environment winning would be a 401 nobody asked
@@ -81,7 +93,9 @@ def signed_in_client(base_url: str, timeout: float | None) -> Albus:
             "`albus login`."
         )
 
-    return bearer_client(base_url, timeout, _current(base_url, stored))
+    return bearer_client(
+        base_url, timeout, organization, _current(base_url, stored)
+    )
 
 
 def public_client(base_url: str, timeout: float | None) -> Albus:
@@ -94,15 +108,20 @@ def public_client(base_url: str, timeout: float | None) -> Albus:
     sign-in changes."""
     global _used
     _used = None
-    return _built(base_url, timeout)
+    return _built(base_url, timeout, None)
 
 
 def bearer_client(
-    base_url: str, timeout: float | None, credential: Credential
+    base_url: str,
+    timeout: float | None,
+    organization: str | None,
+    credential: Credential,
 ) -> Albus:
     """A client on one credential, for `login` reading back the session
     it just stored rather than whatever precedence would pick."""
-    return _client(base_url, timeout, access_token=credential.access_token)
+    return _client(
+        base_url, timeout, organization, access_token=credential.access_token
+    )
 
 
 def credential(tokens: oauth.Tokens, replacing: Credential | None) -> Credential:
@@ -206,6 +225,7 @@ def _shadowing(consequence: str) -> str | None:
 def _client(
     base_url: str,
     timeout: float | None,
+    organization: str | None,
     *,
     api_key: str | None = None,
     access_token: str | None = None,
@@ -215,6 +235,7 @@ def _client(
     return _built(
         base_url,
         timeout,
+        organization,
         api_key=api_key,
         access_token=access_token,
     )
@@ -223,15 +244,19 @@ def _client(
 def _built(
     base_url: str,
     timeout: float | None,
+    organization: str | None,
     *,
     api_key: str | None = None,
     access_token: str | None = None,
 ) -> Albus:
+    headers = {ORGANIZATION_HEADER: organization} if organization else {}
     return Albus(
         api_key=api_key,
         access_token=access_token,
         server_url=base_url,
-        client=httpx.Client(follow_redirects=True, timeout=timeout),
+        client=httpx.Client(
+            follow_redirects=True, timeout=timeout, headers=headers
+        ),
     )
 
 

{albus_cli-0.5.0 → albus_cli-0.7.0}/src/albus_cli/commands/auth.py

@@ -8,9 +8,10 @@ SDK operation: they talk to Auth0 rather than to Albus. See
 from typing import Annotated
 
 import typer
+from albus_sdk import models
 
 from albus_cli import client, credentials, docs, oauth, output
-from albus_cli.context import base_url, sdk, timeout
+from albus_cli.context import base_url, organization, sdk, timeout
 
 NoBrowser = Annotated[
     bool,
@@ -39,11 +40,13 @@ def login(ctx: typer.Context, no_browser: NoBrowser = False) -> None:
 
     # Read the account back through the session just stored, not through
     # precedence: naming the API key's account would be a false report.
-    signed_in = client.bearer_client(api, timeout(ctx), session)
+    signed_in = client.bearer_client(
+        api, timeout(ctx), organization(ctx), session
+    )
     # A browser session authenticates a user, so `/whoami` names one;
     # an account it did not name is not one to claim under "Signed in".
     user = signed_in.auth.whoami().user
-    output.done("Signed in" if user is None else f"Signed in as {user.email}")
+    output.done(_signed_in(user))
     output.field("API", api)
     output.field("Credential", output.abbreviated(credentials.path()))
     if session.refresh_token is None:
@@ -69,6 +72,18 @@ def whoami(ctx: typer.Context) -> None:
     output.emit(sdk(ctx).auth.whoami())
 
 
+def _signed_in(user: models.AuthenticatedUser | None) -> str:
+    """The account and the organization its commands act in, as Albus
+    reports them for the session just stored."""
+    if user is None:
+        return "Signed in"
+
+    if user.active_organization is None:
+        return f"Signed in as {user.email}"
+
+    return f"Signed in as {user.email} in {user.active_organization.name}"
+
+
 def _next_steps() -> None:
     """The last lines a successful sign-in prints, where attention is
     highest: the one command that runs an agent, and the sentence to

albus_cli-0.7.0/src/albus_cli/commands/billing.py

@@ -0,0 +1,67 @@
+"""`albus billing` — the organization's prepaid credits.
+
+`/billing/checkout` is `bearerAuth`-only: an API key cannot spend money, so
+`checkout` takes the browser session with `signed_in_sdk`. Reading the
+balance and the ledger accepts either credential.
+"""
+
+from typing import Annotated
+
+import typer
+
+from albus_cli.context import sdk, signed_in_sdk
+from albus_cli.output import emit
+
+app = typer.Typer(no_args_is_help=True, help="Read and top up prepaid credits.")
+
+After = Annotated[
+    str | None,
+    typer.Option("--after", help="Pagination cursor from a previous page."),
+]
+Limit = Annotated[int, typer.Option("--limit", help="Page size.")]
+
+
+@app.command("balance")
+def balance(ctx: typer.Context) -> None:
+    """Read the organization's credit balance in USD."""
+    emit(sdk(ctx).billing.get_credit_balance())
+
+
+@app.command("ledger")
+def ledger(ctx: typer.Context, after: After = None, limit: Limit = 100) -> None:
+    """List the credit ledger, newest first."""
+    emit(sdk(ctx).billing.list_credit_ledger(after=after, limit=limit))
+
+
+@app.command("checkout")
+def checkout(
+    ctx: typer.Context,
+    amount_usd: Annotated[
+        int,
+        typer.Argument(
+            metavar="AMOUNT_USD", help="Whole US dollars of credit to buy."
+        ),
+    ],
+    success_url: Annotated[
+        str,
+        typer.Option(
+            "--success-url",
+            help="Where the payment page sends the buyer after paying.",
+        ),
+    ],
+    cancel_url: Annotated[
+        str,
+        typer.Option(
+            "--cancel-url",
+            help="Where the payment page sends the buyer who backs out.",
+        ),
+    ],
+) -> None:
+    """Start a credit purchase and print the payment page URL."""
+    emit(
+        signed_in_sdk(ctx).billing.create_checkout(
+            amount_usd=amount_usd,
+            success_url=success_url,
+            cancel_url=cancel_url,
+        )
+    )

albus_cli-0.7.0/src/albus_cli/commands/invites.py

@@ -0,0 +1,54 @@
+"""`albus invites` — the pending invitations into the active organization.
+
+`/organization/invites` is `bearerAuth`-only, like `/tokens`: an API key
+cannot invite a user, so these commands take the browser session with
+`signed_in_sdk`.
+"""
+
+from typing import Annotated, Literal
+
+import typer
+
+from albus_cli.context import signed_in_sdk
+from albus_cli.output import emit
+
+app = typer.Typer(no_args_is_help=True, help="Invite users by email.")
+
+Role = Literal["admin", "member"]
+
+InviteID = Annotated[
+    str, typer.Argument(metavar="ID", help="The invitation ID.")
+]
+
+
+@app.command("list")
+def list_invites(ctx: typer.Context) -> None:
+    """List pending invitations. Requires the admin role."""
+    emit(signed_in_sdk(ctx).invites.list_invites())
+
+
+@app.command("create")
+def create(
+    ctx: typer.Context,
+    email: Annotated[
+        str,
+        typer.Argument(
+            metavar="EMAIL", help="Email address of the person to invite."
+        ),
+    ],
+    role: Annotated[
+        Role | None,
+        typer.Option(
+            "--role",
+            help="Role the invitee joins with. Defaults to member.",
+        ),
+    ] = None,
+) -> None:
+    """Invite a user to join your active organization."""
+    emit(signed_in_sdk(ctx).invites.create_invite(email=email, role=role))
+
+
+@app.command("revoke")
+def revoke(ctx: typer.Context, invite_id: InviteID) -> None:
+    """Revoke a pending invitation. Requires the admin role."""
+    signed_in_sdk(ctx).invites.revoke_invite(id=invite_id)

albus_cli-0.7.0/src/albus_cli/commands/memories.py

@@ -0,0 +1,56 @@
+"""`albus memories` — the memory groups agents share, and what they hold."""
+
+from typing import Annotated
+
+import typer
+
+from albus_cli.context import sdk
+from albus_cli.output import emit
+
+app = typer.Typer(
+    no_args_is_help=True, help="List and delete memory groups and memories."
+)
+
+Group = Annotated[
+    str,
+    typer.Option("--group", help="Memory group key."),
+]
+After = Annotated[
+    str | None,
+    typer.Option("--after", help="Pagination cursor from a previous page."),
+]
+Limit = Annotated[int, typer.Option("--limit", help="Page size.")]
+
+
+@app.command("groups")
+def list_groups(
+    ctx: typer.Context, after: After = None, limit: Limit = 100
+) -> None:
+    """List the organization's memory groups."""
+    emit(sdk(ctx).memories.list_memory_groups(after=after, limit=limit))
+
+
+@app.command("list")
+def list_memories(
+    ctx: typer.Context, group: Group, after: After = None, limit: Limit = 100
+) -> None:
+    """List a group's memories, newest first."""
+    emit(sdk(ctx).memories.list_memories(group=group, after=after, limit=limit))
+
+
+@app.command("delete")
+def delete(
+    ctx: typer.Context,
+    memory_id: Annotated[
+        str, typer.Argument(metavar="ID", help="The memory ID.")
+    ],
+    group: Group,
+) -> None:
+    """Delete one memory of a group, permanently."""
+    sdk(ctx).memories.delete_memory(group=group, id=memory_id)
+
+
+@app.command("delete-group")
+def delete_group(ctx: typer.Context, group: Group) -> None:
+    """Delete every memory of a group."""
+    sdk(ctx).memories.delete_memory_group(group=group)

albus_cli-0.7.0/src/albus_cli/commands/organization.py

@@ -0,0 +1,64 @@
+"""`albus organization` — the organization the commands act in, and its
+members."""
+
+from typing import Annotated, Literal
+
+import typer
+
+from albus_cli.context import sdk
+from albus_cli.output import emit
+
+app = typer.Typer(
+    no_args_is_help=True, help="Manage the organization and its members."
+)
+
+Role = Literal["admin", "member"]
+
+UserID = Annotated[
+    str, typer.Argument(metavar="USER_ID", help="The member's user ID.")
+]
+
+
+@app.command("get")
+def get(ctx: typer.Context) -> None:
+    """Get the organization."""
+    emit(sdk(ctx).organization.get_organization())
+
+
+@app.command("rename")
+def rename(
+    ctx: typer.Context,
+    name: Annotated[
+        str, typer.Argument(metavar="NAME", help="New display name.")
+    ],
+) -> None:
+    """Rename the organization. Requires the admin role."""
+    emit(sdk(ctx).organization.update_organization(name=name))
+
+
+@app.command("members")
+def members(ctx: typer.Context) -> None:
+    """List the organization's members. Requires the admin role."""
+    emit(sdk(ctx).organization.list_organization_members())
+
+
+@app.command("set-role")
+def set_role(
+    ctx: typer.Context,
+    user_id: UserID,
+    role: Annotated[
+        Role, typer.Argument(metavar="ROLE", help="admin or member.")
+    ],
+) -> None:
+    """Set a member's role. Requires the admin role."""
+    emit(
+        sdk(ctx).organization.set_organization_member_role(
+            user_id=user_id, role=role
+        )
+    )
+
+
+@app.command("remove-member")
+def remove_member(ctx: typer.Context, user_id: UserID) -> None:
+    """Remove a member from the organization. Requires the admin role."""
+    sdk(ctx).organization.remove_organization_member(user_id=user_id)

{albus_cli-0.5.0 → albus_cli-0.7.0}/src/albus_cli/commands/sessions.py

@@ -11,7 +11,7 @@ from albus_sdk import models
 from pydantic import ValidationError
 
 from albus_cli.client import client
-from albus_cli.context import base_url, options, sdk
+from albus_cli.context import base_url, options, organization, sdk
 from albus_cli.output import emit
 
 app = typer.Typer(no_args_is_help=True, help="Run and inspect sessions.")
@@ -215,7 +215,7 @@ def run(
     )
     timeout = options(ctx).timeout
     # A waiting invocation long-polls, so it outlives the request timeout.
-    albus = client(base_url(ctx), None if wait else timeout)
+    albus = client(base_url(ctx), None if wait else timeout, organization(ctx))
     response = albus.sessions.run_session(
         id=session_id,
         user_prompt=prompt,
@@ -270,6 +270,12 @@ def audit(
     )
 
 
+@app.command("cancel")
+def cancel(ctx: typer.Context, session_id: SessionID) -> None:
+    """Cancel the invocation running for a session."""
+    emit(sdk(ctx).sessions.cancel_session(id=session_id))
+
+
 @app.command("delete")
 def delete(ctx: typer.Context, session_id: SessionID) -> None:
     """Delete a session."""

{albus_cli-0.5.0 → albus_cli-0.7.0}/src/albus_cli/commands/status.py

@@ -15,7 +15,7 @@ import typer
 from albus_sdk import errors
 
 from albus_cli import client, credentials, oauth, output
-from albus_cli.context import base_url, timeout
+from albus_cli.context import base_url, organization, timeout
 
 # Everything that answers "the credential does not work": Albus refusing it, a
 # stored session that cannot be renewed, an Auth0 tenant that is unconfigured
@@ -77,7 +77,7 @@ def _accepted(ctx: typer.Context, api: str) -> dict[str, Any]:
     principal — the signed-in user, or the API key and the organization
     it acts in — so one operation both verifies the credential the next
     command sends and reports who it belongs to."""
-    caller = client.client(api, timeout(ctx)).auth.whoami()
+    caller = client.client(api, timeout(ctx), organization(ctx)).auth.whoami()
     return {
         "authenticated": True,
         "caller": caller.model_dump(mode="json", exclude_none=True),