feat: add per-project local/cloud routing with API key auth (#555)

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/basic_memory/cli/commands/cloud/core_commands.py

@@ -210,3 +210,79 @@ def promo(enabled: bool = typer.Option(True, "--on/--off", help="Enable or disab
         console.print("[green]Cloud promo messages enabled[/green]")
     else:
         console.print("[yellow]Cloud promo messages disabled[/yellow]")
+
+
+@cloud_app.command("set-key")
+def set_key(
+    api_key: str = typer.Argument(..., help="API key (bmc_ prefixed) for cloud access"),
+) -> None:
+    """Save a cloud API key for per-project cloud routing.
+
+    The API key is account-level and used by projects set to cloud mode.
+    Create a key in the web app or use 'bm cloud create-key'.
+
+    Example:
+      bm cloud set-key bmc_abc123...
+    """
+    if not api_key.startswith("bmc_"):
+        console.print("[red]Error: API key must start with 'bmc_'[/red]")
+        raise typer.Exit(1)
+
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    config.cloud_api_key = api_key
+    config_manager.save_config(config)
+
+    console.print("[green]API key saved[/green]")
+    console.print("[dim]Projects set to cloud mode will use this key for authentication[/dim]")
+    console.print("[dim]Set a project to cloud mode: bm project set-cloud <name>[/dim]")
+
+
+@cloud_app.command("create-key")
+def create_key(
+    name: str = typer.Argument(..., help="Human-readable name for the API key"),
+) -> None:
+    """Create a new cloud API key and save it locally.
+
+    Requires active OAuth session (run 'bm cloud login' first).
+    The key is created via the cloud API and saved to local config.
+
+    Example:
+      bm cloud create-key "my-laptop"
+    """
+
+    async def _create_key():
+        _, _, host_url = get_cloud_config()
+        host_url = host_url.rstrip("/")
+
+        console.print(f"[dim]Creating API key '{name}'...[/dim]")
+        response = await make_api_request(
+            method="POST",
+            url=f"{host_url}/api/keys",
+            json_data={"name": name},
+        )
+
+        key_data = response.json()
+        api_key = key_data.get("key")
+        if not api_key:
+            console.print("[red]Error: No key returned from API[/red]")
+            raise typer.Exit(1)
+
+        # Save to config
+        config_manager = ConfigManager()
+        config = config_manager.load_config()
+        config.cloud_api_key = api_key
+        config_manager.save_config(config)
+
+        console.print(f"[green]API key '{name}' created and saved[/green]")
+        console.print("[dim]Projects set to cloud mode will use this key for authentication[/dim]")
+        console.print("[dim]Set a project to cloud mode: bm project set-cloud <name>[/dim]")
+
+    try:
+        run_with_cleanup(_create_key())
+    except CloudAPIError as e:
+        console.print(f"[red]Error creating API key: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)

src/basic_memory/cli/commands/project.py

@@ -13,7 +13,7 @@ from rich.table import Table
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import get_project_info, run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
-from basic_memory.config import ConfigManager
+from basic_memory.config import ConfigManager, ProjectMode
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.tools.utils import call_delete, call_get, call_patch, call_post, call_put
 from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse
@@ -77,6 +77,7 @@ def list_projects(
         table = Table(title="Basic Memory Projects")
         table.add_column("Name", style="cyan")
         table.add_column("Path", style="green")
+        table.add_column("Mode", style="blue")
 
         # Add Local Path column if in cloud mode and not forcing local
         if config.cloud_mode_enabled and not local:
@@ -90,9 +91,10 @@ def list_projects(
         for project in result.projects:
             is_default = "[X]" if project.is_default else ""
             normalized_path = normalize_project_path(project.path)
+            project_mode = config.get_project_mode(project.name).value
 
             # Build row based on mode
-            row = [project.name, format_path(normalized_path)]
+            row = [project.name, format_path(normalized_path), project_mode]
 
             # Add local path if in cloud mode and not forcing local
             if config.cloud_mode_enabled and not local:
@@ -511,6 +513,74 @@ def move_project(
         raise typer.Exit(1)
 
 
+@project_app.command("set-cloud")
+def set_cloud(
+    name: str = typer.Argument(..., help="Name of the project to route through cloud"),
+) -> None:
+    """Set a project to cloud mode (route through cloud API).
+
+    Requires either an API key or an active OAuth session.
+
+    Examples:
+      bm cloud set-key bmc_abc123...   # save API key, then:
+      bm project set-cloud research    # route "research" through cloud
+
+      bm cloud login                   # OAuth login, then:
+      bm project set-cloud research    # route "research" through cloud
+    """
+    from basic_memory.cli.auth import CLIAuth
+
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    # Validate project exists in config
+    if name not in config.projects:
+        console.print(f"[red]Error: Project '{name}' not found in config[/red]")
+        raise typer.Exit(1)
+
+    # Validate credentials: API key or OAuth session
+    has_api_key = bool(config.cloud_api_key)
+    has_oauth = False
+    if not has_api_key:
+        auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+        has_oauth = auth.load_tokens() is not None
+
+    if not has_api_key and not has_oauth:
+        console.print("[red]Error: No cloud credentials found[/red]")
+        console.print("[dim]Run 'bm cloud set-key <key>' or 'bm cloud login' first[/dim]")
+        raise typer.Exit(1)
+
+    config.set_project_mode(name, ProjectMode.CLOUD)
+    config_manager.save_config(config)
+
+    console.print(f"[green]Project '{name}' set to cloud mode[/green]")
+    console.print("[dim]MCP tools and CLI commands for this project will route through cloud[/dim]")
+
+
+@project_app.command("set-local")
+def set_local(
+    name: str = typer.Argument(..., help="Name of the project to revert to local mode"),
+) -> None:
+    """Revert a project to local mode (use in-process ASGI transport).
+
+    Example:
+      bm project set-local research
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    # Validate project exists in config
+    if name not in config.projects:
+        console.print(f"[red]Error: Project '{name}' not found in config[/red]")
+        raise typer.Exit(1)
+
+    config.set_project_mode(name, ProjectMode.LOCAL)
+    config_manager.save_config(config)
+
+    console.print(f"[green]Project '{name}' set to local mode[/green]")
+    console.print("[dim]MCP tools and CLI commands for this project will use local transport[/dim]")
+
+
 @project_app.command("sync")
 def sync_project_command(
     name: str = typer.Option(..., "--name", help="Project name to sync"),