feat: CLI for permission elevation

Signed-off-by: Tomas Weiss <[email protected]>

Author: tomkis

apps/agentstack-cli/src/agentstack_cli/__init__.py

@@ -15,6 +15,7 @@
 import agentstack_cli.commands.platform
 import agentstack_cli.commands.self
 import agentstack_cli.commands.server
+import agentstack_cli.commands.user
 from agentstack_cli.async_typer import AliasGroup, AsyncTyper
 from agentstack_cli.configuration import Configuration
 
@@ -48,6 +49,7 @@ def get_help(self, ctx):
 │ model           Configure 15+ LLM providers                                │
 │ platform        Start, stop, or delete local platform                      │
 │ server          Connect to remote Agent Stack servers                      │
+│ user            Manage users and roles                                     │
 │ self version    Show Agent Stack CLI and Platform version                  │
 │ self upgrade    Upgrade Agent Stack CLI and Platform                       │
 │ self uninstall  Uninstall Agent Stack CLI and Platform                     │
@@ -84,6 +86,12 @@ def get_help(self, ctx):
     help="Manage Agent Stack installation.",
     hidden=True,
 )
+app.add_typer(
+    agentstack_cli.commands.user.app,
+    name="user",
+    no_args_is_help=True,
+    help="Manage users.",
+)
 
 
 agent_alias = deepcopy(agentstack_cli.commands.agent.app)

apps/agentstack-cli/src/agentstack_cli/commands/user.py

@@ -0,0 +1,96 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+import typing
+from datetime import datetime
+
+import typer
+from agentstack_sdk.platform import User
+from agentstack_sdk.platform.user import UserRole
+from rich.table import Column
+
+from agentstack_cli.async_typer import AsyncTyper, console, create_table
+from agentstack_cli.configuration import Configuration
+from agentstack_cli.utils import announce_server_action, confirm_server_action
+
+app = AsyncTyper()
+configuration = Configuration()
+
+
+@app.command("list")
+async def list_users(
+    email: typing.Annotated[str | None, typer.Option(help="Filter by email (case-insensitive partial match)")] = None,
+    limit: typing.Annotated[int, typer.Option(help="Results per page (1-100)")] = 40,
+    after: typing.Annotated[str | None, typer.Option(help="Pagination cursor (page_token)")] = None,
+):
+    """List platform users (admin only)."""
+    announce_server_action("Listing users on")
+
+    async with configuration.use_platform_client():
+        result = await User.list(email=email, limit=limit, page_token=after)
+
+        items = result.items
+        has_more = result.has_more
+        next_page_token = result.next_page_token
+
+    with create_table(
+        Column("ID", style="yellow"),
+        Column("Email"),
+        Column("Role"),
+        Column("Created"),
+        Column("Role Updated"),
+        no_wrap=True,
+    ) as table:
+        for user in items:
+            role_display = {
+                "admin": "[red]admin[/red]",
+                "developer": "[cyan]developer[/cyan]",
+                "user": "user",
+            }.get(user.role, user.role)
+
+            created_at = _format_date(user.created_at)
+            role_updated_at = _format_date(user.role_updated_at) if user.role_updated_at else "-"
+
+            table.add_row(
+                user.id,
+                user.email,
+                role_display,
+                created_at,
+                role_updated_at,
+            )
+
+    console.print()
+    console.print(table)
+
+    if has_more and next_page_token:
+        console.print(f"\n[dim]Use --after {next_page_token} to see more[/dim]")
+
+
+@app.command("set-role")
+async def set_role(
+    user_id: typing.Annotated[str, typer.Argument(help="User UUID")],
+    role: typing.Annotated[UserRole, typer.Option("--role", "-r", help="Target role")],
+    yes: typing.Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation prompts.")] = False,
+):
+    """Change user role (admin only)."""
+    url = announce_server_action(f"Changing user {user_id} to role '{role}' on")
+    await confirm_server_action("Proceed with role change on", url=url, yes=yes)
+
+    async with configuration.use_platform_client():
+        result = await User.set_role(user_id, UserRole(role))
+
+        role_display = {
+            "admin": "[red]admin[/red]",
+            "developer": "[cyan]developer[/cyan]",
+            "user": "user",
+        }.get(result.new_role, result.new_role)
+
+        console.success(
+            f"User role updated to [cyan]{role_display}[/cyan] (version [yellow]{result.role_version}[/yellow])"
+        )
+
+
+def _format_date(dt: datetime | None) -> str:
+    if not dt:
+        return "-"
+    return dt.strftime("%Y-%m-%d %H:%M")

apps/agentstack-sdk-py/src/agentstack_sdk/platform/__init__.py

@@ -7,5 +7,6 @@
 from .model_provider import *
 from .provider import *
 from .provider_build import *
+from .user import *
 from .user_feedback import *
 from .vector_store import *

apps/agentstack-sdk-py/src/agentstack_sdk/platform/user.py

@@ -3,23 +3,69 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from enum import StrEnum
 
 import pydantic
 
 from agentstack_sdk.platform.client import PlatformClient, get_platform_client
+from agentstack_sdk.platform.common import PaginatedResult
+
+
+class UserRole(StrEnum):
+    ADMIN = "admin"
+    DEVELOPER = "developer"
+    USER = "user"
+
+
+class ChangeRoleResponse(pydantic.BaseModel):
+    user_id: str
+    new_role: UserRole
+    role_version: int
 
 
 class User(pydantic.BaseModel):
     id: str
-    role: Literal["admin", "developer", "user"]
+    role: UserRole
     email: str
     created_at: pydantic.AwareDatetime
+    role_updated_at: pydantic.AwareDatetime | None = None
 
     @staticmethod
     async def get(*, client: PlatformClient | None = None) -> User:
-        """Get the current user information."""
         async with client or get_platform_client() as client:
             return pydantic.TypeAdapter(User).validate_python(
                 (await client.get(url="/api/v1/user")).raise_for_status().json()
             )
+
+    @staticmethod
+    async def list(
+        *,
+        email: str | None = None,
+        limit: int = 40,
+        page_token: str | None = None,
+        client: PlatformClient | None = None,
+    ) -> PaginatedResult[User]:
+        async with client or get_platform_client() as client:
+            params: dict[str, int | str] = {"limit": limit}
+            if email:
+                params["email"] = email
+            if page_token:
+                params["page_token"] = page_token
+
+            return pydantic.TypeAdapter(PaginatedResult[User]).validate_python(
+                (await client.get(url="/api/v1/users", params=params)).raise_for_status().json()
+            )
+
+    @staticmethod
+    async def set_role(
+        user_id: str,
+        new_role: UserRole,
+        *,
+        client: PlatformClient | None = None,
+    ) -> ChangeRoleResponse:
+        async with client or get_platform_client() as client:
+            return pydantic.TypeAdapter(ChangeRoleResponse).validate_python(
+                (await client.put(url=f"/api/v1/users/{user_id}/role", json={"new_role": new_role}))
+                .raise_for_status()
+                .json()
+            )

apps/agentstack-server/src/agentstack_server/api/routes/users.py

@@ -40,7 +40,7 @@ async def list_users(
     )
 
 
-@router.put("/users/{user_id}/role", response_model=ChangeRoleResponse)
+@router.put("/{user_id}/role", response_model=ChangeRoleResponse)
 async def change_user_role(
     user_id: UUID,
     request: ChangeRoleRequest,