meshagent-cli 0.7.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

meshagent/cli/oauth2.py

@@ -18,16 +18,27 @@ app = async_typer.AsyncTyper(help="OAuth2 test commands")
 @app.async_command("request")
 async def oauth2(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
-    from_participant_id: Annotated[str, typer.Option()],
-    client_id: Annotated[str, typer.Option()],
-    authorization_endpoint: Annotated[str, typer.Option()],
-    token_endpoint: Annotated[str, typer.Option()],
-    scopes: Annotated[Optional[str], typer.Option()] = None,
-    client_secret: Annotated[Optional[str], typer.Option()],
-    redirect_uri: Annotated[Optional[str], typer.Option()],
-    pkce: Annotated[bool, typer.Option()] = True,
+    from_participant_id: Annotated[
+        str,
+        typer.Option(..., help="Participant ID to request the token from"),
+    ],
+    client_id: Annotated[str, typer.Option(..., help="OAuth client ID")],
+    authorization_endpoint: Annotated[
+        str, typer.Option(..., help="OAuth authorization endpoint URL")
+    ],
+    token_endpoint: Annotated[str, typer.Option(..., help="OAuth token endpoint URL")],
+    scopes: Annotated[
+        Optional[str], typer.Option(help="Comma-separated OAuth scopes")
+    ] = None,
+    client_secret: Annotated[
+        Optional[str], typer.Option(help="OAuth client secret (if required)")
+    ],
+    redirect_uri: Annotated[
+        Optional[str], typer.Option(help="Redirect URI for the OAuth flow")
+    ],
+    pkce: Annotated[bool, typer.Option(help="Use PKCE (recommended)")] = True,
 ):
     """
     Run an OAuth2 request test between two participants in the same room.
@@ -72,16 +83,26 @@ async def oauth2(
 @app.async_command("get")
 async def get(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
-    delegated_to: Annotated[str, typer.Option()],
-    client_id: Annotated[str, typer.Option()],
-    authorization_endpoint: Annotated[str, typer.Option()],
-    token_endpoint: Annotated[str, typer.Option()],
-    scopes: Annotated[Optional[str], typer.Option()] = None,
-    client_secret: Annotated[Optional[str], typer.Option()],
-    redirect_uri: Annotated[Optional[str], typer.Option()],
-    pkce: Annotated[bool, typer.Option()] = True,
+    delegated_to: Annotated[
+        str, typer.Option(..., help="Participant ID to delegate the token to")
+    ],
+    client_id: Annotated[str, typer.Option(..., help="OAuth client ID")],
+    authorization_endpoint: Annotated[
+        str, typer.Option(..., help="OAuth authorization endpoint URL")
+    ],
+    token_endpoint: Annotated[str, typer.Option(..., help="OAuth token endpoint URL")],
+    scopes: Annotated[
+        Optional[str], typer.Option(help="Comma-separated OAuth scopes")
+    ] = None,
+    client_secret: Annotated[
+        Optional[str], typer.Option(help="OAuth client secret (if required)")
+    ],
+    redirect_uri: Annotated[
+        Optional[str], typer.Option(help="Redirect URI for the OAuth flow")
+    ],
+    pkce: Annotated[bool, typer.Option(help="Use PKCE (recommended)")] = True,
 ):
     """
     Run an OAuth2 request test between two participants in the same room.
@@ -124,7 +145,7 @@ async def get(
 @app.async_command("list")
 async def list(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
 ):
     """
@@ -159,10 +180,12 @@ async def list(
 @app.async_command("delete")
 async def delete(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
     id: str,
-    delegated_to: Annotated[Optional[str], typer.Option()] = None,
+    delegated_to: Annotated[
+        str, typer.Option(help="The value of the delegated_to field of the secret")
+    ],
 ):
     """
     delete a secret

meshagent/cli/participant_token.py

@@ -10,13 +10,13 @@ from meshagent.api.participant_token import ParticipantTokenSpec
 from pydantic_yaml import parse_yaml_raw_as
 from meshagent.cli.common_options import ProjectIdOption
 
-app = async_typer.AsyncTyper()
+app = async_typer.AsyncTyper(help="Generate participant tokens (JWTs)")
 
 
-@app.async_command("generate")
+@app.async_command("generate", help="Generate a participant token (JWT) from a spec")
 async def generate(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     output: Annotated[
         Optional[str],
         typer.Option("--output", "-o", help="File path to a file"),
@@ -30,6 +30,8 @@ async def generate(
         typer.Option("--key", help="an api key to sign the token with"),
     ] = None,
 ):
+    """Generate a signed participant token (JWT) from a YAML spec."""
+
     project_id = await resolve_project_id(project_id=project_id)
     key = await resolve_key(project_id=project_id, key=key)
 

meshagent/cli/port.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+
+
+from typing import Annotated
+
+import typer
+
+from meshagent.cli import async_typer
+from meshagent.cli.common_options import ProjectIdOption
+from meshagent.cli.helper import get_client, resolve_project_id
+
+from meshagent.api.port_forward import port_forward
+
+app = async_typer.AsyncTyper(help="Port forwarding into room containers")
+
+
+@app.async_command("forward", help="Forward a container port to localhost")
+async def forward(
+    *,
+    project_id: ProjectIdOption,
+    room: Annotated[
+        str,
+        typer.Option(
+            "--room",
+            "-r",
+            help="Room name containing the target container",
+        ),
+    ],
+    container_id: Annotated[
+        str,
+        typer.Option(
+            "--container-id",
+            "-c",
+            help="Container ID to port-forward into",
+        ),
+    ],
+    port: Annotated[
+        str,
+        typer.Option(
+            "--port",
+            "-p",
+            help="Port mapping in the form LOCAL:REMOTE",
+        ),
+    ],
+):
+    """Create a local TCP listener forwarding into a room container."""
+
+    client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id)
+
+        connection = await client.connect_room(project_id=project_id, room=room)
+
+        ports = port.split(":")
+
+        handler = await port_forward(
+            listen_port=int(ports[0]),
+            port=int(ports[1]),
+            container_id=container_id,
+            token=connection.jwt,
+        )
+
+        await asyncio.sleep(10000)
+
+        await handler.close()
+
+    finally:
+        await client.close()

meshagent/cli/queue.py

@@ -20,7 +20,7 @@ app = async_typer.AsyncTyper(help="Use queues in a room")
 @app.async_command("send")
 async def send(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
     queue: Annotated[str, typer.Option(..., help="Queue name")],
     json: Optional[str] = typer.Option(..., help="a JSON message to send to the queue"),
@@ -60,7 +60,7 @@ async def send(
 @app.async_command("receive")
 async def receive(
     *,
-    project_id: ProjectIdOption = None,
+    project_id: ProjectIdOption,
     room: RoomOption,
     queue: Annotated[str, typer.Option(..., help="Queue name")],
 ):

meshagent/cli/room.py

@@ -1,214 +1,22 @@
-# rooms_cli.py (add to the same module or import into your CLI package)
-
-import typer
-from rich import print
-from typing import Annotated, Optional
-import json
-
 from meshagent.cli import async_typer
-from meshagent.cli.common_options import ProjectIdOption
-from meshagent.cli.helper import (
-    get_client,
-    resolve_project_id,
-    resolve_room,
+from meshagent.cli import database
+from meshagent.cli import queue
+from meshagent.cli import agent
+from meshagent.cli import messaging
+from meshagent.cli import storage
+from meshagent.cli import developer
+from meshagent.cli import cli_secrets
+from meshagent.cli import containers
+
+app = async_typer.AsyncTyper(help="Operate within a room")
+
+app.add_typer(agent.app, name="agents", help="Interact with agents and toolkits")
+app.add_typer(cli_secrets.app, name="secret", help="Manage secrets for your project")
+app.add_typer(queue.app, name="queue", help="Use queues in a room")
+app.add_typer(messaging.app, name="messaging", help="Send and receive messages")
+app.add_typer(storage.app, name="storage", help="Manage storage for a room")
+app.add_typer(developer.app, name="developer", help="Developer utilities for a room")
+app.add_typer(database.app, name="database", help="Manage database tables in a room")
+app.add_typer(
+    containers.app, name="container", help="Manage containers and images in a room"
 )
-from meshagent.api import RoomException
-
-app = async_typer.AsyncTyper()
-
-# ---------------------------
-# Helpers
-# ---------------------------
-
-
-async def _resolve_room_id_or_fail(
-    account_client, *, project_id: str, room_id: Optional[str], room_name: Optional[str]
-) -> str:
-    """
-    If room_id is provided, return it.
-    Else, resolve via room_name -> account_client.get_room(...).id
-    """
-    if room_id:
-        return room_id
-    if not room_name:
-        raise RoomException("You must provide either --id or --name.")
-    room = await account_client.get_room(project_id=project_id, name=room_name)
-    return room.id
-
-
-def _maybe_parse_json(label: str, s: Optional[str]):
-    if s is None:
-        return None
-    try:
-        return json.loads(s)
-    except json.JSONDecodeError as e:
-        raise RoomException(f"Invalid {label} JSON: {e}") from e
-
-
-# ---------------------------
-# Commands
-# ---------------------------
-
-
-@app.async_command("create")
-async def room_create_command(
-    *,
-    project_id: ProjectIdOption = None,
-    name: Annotated[str, typer.Option(..., help="Room name")],
-    if_not_exists: Annotated[
-        bool, typer.Option(help="Do not error if the room already exists")
-    ] = False,
-    metadata: Annotated[
-        Optional[str], typer.Option(help="Optional JSON object for room metadata")
-    ] = None,
-):
-    """
-    Create a room in the project.
-    """
-    account_client = await get_client()
-    try:
-        project_id = await resolve_project_id(project_id=project_id)
-
-        meta_obj = _maybe_parse_json("metadata", metadata)
-
-        print(f"[bold green]Creating room {name}[/bold green]")
-        room = await account_client.create_room(
-            project_id=project_id,
-            name=name,
-            if_not_exists=if_not_exists,
-            metadata=meta_obj,
-        )
-
-        print(
-            json.dumps(
-                {"id": room.id, "name": room.name, "metadata": room.metadata}, indent=2
-            )
-        )
-
-    except RoomException as ex:
-        print(f"[red]{ex}[/red]")
-        raise typer.Exit(1)
-    finally:
-        await account_client.close()
-
-
-@app.async_command("delete")
-async def room_delete_command(
-    *,
-    project_id: ProjectIdOption = None,
-    id: Annotated[Optional[str], typer.Option(help="Room ID (preferred)")] = None,
-    name: Optional[str] = None,
-):
-    """
-    Delete a room by ID (or by name if --name is supplied).
-    """
-    account_client = await get_client()
-    try:
-        project_id = await resolve_project_id(project_id=project_id)
-        room_name = resolve_room(name) if name else None
-        rid = await _resolve_room_id_or_fail(
-            account_client, project_id=project_id, room_id=id, room_name=room_name
-        )
-
-        print(f"[bold yellow]Deleting room id={rid}...[/bold yellow]")
-        await account_client.delete_room(project_id=project_id, room_id=rid)
-        print("[bold cyan]Room deleted.[/bold cyan]")
-    except RoomException as ex:
-        print(f"[red]{ex}[/red]")
-        raise typer.Exit(1)
-    finally:
-        await account_client.close()
-
-
-@app.async_command("update")
-async def room_update_command(
-    *,
-    project_id: ProjectIdOption = None,
-    id: Annotated[Optional[str], typer.Option(help="Room ID (preferred)")] = None,
-    name: Optional[str] = None,
-    new_name: Annotated[str, typer.Option(..., help="New room name")],
-):
-    """
-    Update a room's name (ID is preferred; name will be resolved to ID if needed).
-    """
-    account_client = await get_client()
-    try:
-        project_id = await resolve_project_id(project_id=project_id)
-        room_name = resolve_room(name) if name else None
-        rid = await _resolve_room_id_or_fail(
-            account_client, project_id=project_id, room_id=id, room_name=room_name
-        )
-
-        print(
-            f"[bold green]Updating room id={rid} -> name='{new_name}'...[/bold green]"
-        )
-        await account_client.update_room(
-            project_id=project_id, room_id=rid, name=new_name
-        )
-        print("[bold cyan]Room updated.[/bold cyan]")
-    except RoomException as ex:
-        print(f"[red]{ex}[/red]")
-        raise typer.Exit(1)
-    finally:
-        await account_client.close()
-
-
-@app.async_command("list")
-async def room_list_command(
-    *,
-    project_id: ProjectIdOption = None,
-    limit: Annotated[
-        int, typer.Option(help="Max rooms to return", min=1, max=500)
-    ] = 50,
-    offset: Annotated[int, typer.Option(help="Offset for pagination", min=0)] = 0,
-    order_by: Annotated[
-        str, typer.Option(help='Order by column (e.g. "room_name", "created_at")')
-    ] = "room_name",
-):
-    """
-    List rooms in the project.
-    """
-    account_client = await get_client()
-    try:
-        project_id = await resolve_project_id(project_id=project_id)
-        print("[bold green]Fetching rooms...[/bold green]")
-
-        rooms = await account_client.list_rooms(
-            project_id=project_id,
-            limit=limit,
-            offset=offset,
-            order_by=order_by,
-        )
-        output = [{"id": r.id, "name": r.name, "metadata": r.metadata} for r in rooms]
-        print(json.dumps(output, indent=2))
-    except RoomException as ex:
-        print(f"[red]{ex}[/red]")
-        raise typer.Exit(1)
-    finally:
-        await account_client.close()
-
-
-@app.async_command("get")
-async def room_get_command(
-    *,
-    project_id: ProjectIdOption = None,
-    name: Optional[str] = None,
-):
-    """
-    Get a single room by name (handy for resolving the ID).
-    """
-    account_client = await get_client()
-    try:
-        project_id = await resolve_project_id(project_id=project_id)
-        room_name = resolve_room(name)
-
-        print(f"[bold green]Fetching room '{room_name}'...[/bold green]")
-        r = await account_client.get_room(project_id=project_id, name=room_name)
-        print(
-            json.dumps({"id": r.id, "name": r.name, "metadata": r.metadata}, indent=2)
-        )
-    except RoomException as ex:
-        print(f"[red]{ex}[/red]")
-        raise typer.Exit(1)
-    finally:
-        await account_client.close()

meshagent/cli/rooms.py

@@ -0,0 +1,214 @@
+# rooms_cli.py (add to the same module or import into your CLI package)
+
+import typer
+from rich import print
+from typing import Annotated, Optional
+import json
+
+from meshagent.cli import async_typer
+from meshagent.cli.common_options import ProjectIdOption
+from meshagent.cli.helper import (
+    get_client,
+    resolve_project_id,
+    resolve_room,
+)
+from meshagent.api import RoomException
+
+app = async_typer.AsyncTyper(help="Create, list, and manage rooms in a project")
+
+# ---------------------------
+# Helpers
+# ---------------------------
+
+
+async def _resolve_room_id_or_fail(
+    account_client, *, project_id: str, room_id: Optional[str], room_name: Optional[str]
+) -> str:
+    """
+    If room_id is provided, return it.
+    Else, resolve via room_name -> account_client.get_room(...).id
+    """
+    if room_id:
+        return room_id
+    if not room_name:
+        raise RoomException("You must provide either --id or --name.")
+    room = await account_client.get_room(project_id=project_id, name=room_name)
+    return room.id
+
+
+def _maybe_parse_json(label: str, s: Optional[str]):
+    if s is None:
+        return None
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError as e:
+        raise RoomException(f"Invalid {label} JSON: {e}") from e
+
+
+# ---------------------------
+# Commands
+# ---------------------------
+
+
+@app.async_command("create")
+async def room_create_command(
+    *,
+    project_id: ProjectIdOption,
+    name: Annotated[str, typer.Option(..., help="Room name")],
+    if_not_exists: Annotated[
+        bool, typer.Option(help="Do not error if the room already exists")
+    ] = False,
+    metadata: Annotated[
+        Optional[str], typer.Option(help="Optional JSON object for room metadata")
+    ] = None,
+):
+    """
+    Create a room in the project.
+    """
+    account_client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id=project_id)
+
+        meta_obj = _maybe_parse_json("metadata", metadata)
+
+        print(f"[bold green]Creating room {name}[/bold green]")
+        room = await account_client.create_room(
+            project_id=project_id,
+            name=name,
+            if_not_exists=if_not_exists,
+            metadata=meta_obj,
+        )
+
+        print(
+            json.dumps(
+                {"id": room.id, "name": room.name, "metadata": room.metadata}, indent=2
+            )
+        )
+
+    except RoomException as ex:
+        print(f"[red]{ex}[/red]")
+        raise typer.Exit(1)
+    finally:
+        await account_client.close()
+
+
+@app.async_command("delete")
+async def room_delete_command(
+    *,
+    project_id: ProjectIdOption,
+    id: Annotated[Optional[str], typer.Option(help="Room ID (preferred)")] = None,
+    name: Optional[str] = None,
+):
+    """
+    Delete a room by ID (or by name if --name is supplied).
+    """
+    account_client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id=project_id)
+        room_name = resolve_room(name) if name else None
+        rid = await _resolve_room_id_or_fail(
+            account_client, project_id=project_id, room_id=id, room_name=room_name
+        )
+
+        print(f"[bold yellow]Deleting room id={rid}...[/bold yellow]")
+        await account_client.delete_room(project_id=project_id, room_id=rid)
+        print("[bold cyan]Room deleted.[/bold cyan]")
+    except RoomException as ex:
+        print(f"[red]{ex}[/red]")
+        raise typer.Exit(1)
+    finally:
+        await account_client.close()
+
+
+@app.async_command("update")
+async def room_update_command(
+    *,
+    project_id: ProjectIdOption,
+    id: Annotated[Optional[str], typer.Option(help="Room ID (preferred)")] = None,
+    name: Optional[str] = None,
+    new_name: Annotated[str, typer.Option(..., help="New room name")],
+):
+    """
+    Update a room's name (ID is preferred; name will be resolved to ID if needed).
+    """
+    account_client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id=project_id)
+        room_name = resolve_room(name) if name else None
+        rid = await _resolve_room_id_or_fail(
+            account_client, project_id=project_id, room_id=id, room_name=room_name
+        )
+
+        print(
+            f"[bold green]Updating room id={rid} -> name='{new_name}'...[/bold green]"
+        )
+        await account_client.update_room(
+            project_id=project_id, room_id=rid, name=new_name
+        )
+        print("[bold cyan]Room updated.[/bold cyan]")
+    except RoomException as ex:
+        print(f"[red]{ex}[/red]")
+        raise typer.Exit(1)
+    finally:
+        await account_client.close()
+
+
+@app.async_command("list")
+async def room_list_command(
+    *,
+    project_id: ProjectIdOption,
+    limit: Annotated[
+        int, typer.Option(help="Max rooms to return", min=1, max=500)
+    ] = 50,
+    offset: Annotated[int, typer.Option(help="Offset for pagination", min=0)] = 0,
+    order_by: Annotated[
+        str, typer.Option(help='Order by column (e.g. "room_name", "created_at")')
+    ] = "room_name",
+):
+    """
+    List rooms in the project.
+    """
+    account_client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id=project_id)
+        print("[bold green]Fetching rooms...[/bold green]")
+
+        rooms = await account_client.list_rooms(
+            project_id=project_id,
+            limit=limit,
+            offset=offset,
+            order_by=order_by,
+        )
+        output = [{"id": r.id, "name": r.name, "metadata": r.metadata} for r in rooms]
+        print(json.dumps(output, indent=2))
+    except RoomException as ex:
+        print(f"[red]{ex}[/red]")
+        raise typer.Exit(1)
+    finally:
+        await account_client.close()
+
+
+@app.async_command("get")
+async def room_get_command(
+    *,
+    project_id: ProjectIdOption,
+    name: Optional[str] = None,
+):
+    """
+    Get a single room by name (handy for resolving the ID).
+    """
+    account_client = await get_client()
+    try:
+        project_id = await resolve_project_id(project_id=project_id)
+        room_name = resolve_room(name)
+
+        print(f"[bold green]Fetching room '{room_name}'...[/bold green]")
+        r = await account_client.get_room(project_id=project_id, name=room_name)
+        print(
+            json.dumps({"id": r.id, "name": r.name, "metadata": r.metadata}, indent=2)
+        )
+    except RoomException as ex:
+        print(f"[red]{ex}[/red]")
+        raise typer.Exit(1)
+    finally:
+        await account_client.close()