feat: add cloud mode integration to CLI commands with integration tests

Add runtime cloud_mode_enabled checks to all CLI commands that require authentication. Commands now conditionally authenticate based on whether cloud mode is enabled, allowing seamless operation in both local and cloud modes.

Changes:
- Add cloud_mode_enabled checks to list_projects, remove_project, run_sync, get_project_info, run_status
- Remove auth from set_default_project (local-only command)
- Create 9 CLI integration tests in test-int/cli/ (project, sync, version commands)
- Replace mock-heavy CLI tests with integration tests (deleted 5 mock test files)
- Update SPEC-9 Phase 4.2 with completed cloud mode integration tasks

All tests passing: 58 total (49 existing + 9 new integration tests)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: phernandez

specs/SPEC-9 Multi-Project Bidirectional Sync Architecture.md

@@ -165,6 +165,11 @@ This spec affects:
 - [x] `bm cloud logout`: Clear `BASIC_MEMORY_PROXY_URL` environment variable
 - [x] `bm cloud status`: Show current mode (local/cloud), connection status
 
+**1.4 Skip Initialization in Cloud Mode** ✅
+- [x] Update `ensure_initialization()` to check `cloud_mode` and return early
+- [x] Document that `config.projects` is only used in local mode
+- [x] Cloud manages its own projects via API, no local reconciliation needed
+
 ### Phase 2: Bisync Updates (Multi-Project)
 
 **2.1 Remove RCLONE_TEST Files** ✅
@@ -192,6 +197,16 @@ This spec affects:
 - [x] Add `validate_bisync_directory()` safety check
 - [x] Update `get_default_mount_path()` to return fixed `~/basic-memory-cloud/`
 
+**2.5 Sync/Status API Infrastructure** ✅ (commit d48b1dc)
+- [x] Create `POST /{project}/project/sync` endpoint for background sync
+- [x] Create `POST /{project}/project/status` endpoint for scan-only status
+- [x] Create `SyncReportResponse` Pydantic schema
+- [x] Refactor CLI `sync` command to use API endpoint
+- [x] Refactor CLI `status` command to use API endpoint
+- [x] Create `command_utils.py` with shared `run_sync()` function
+- [x] Update `notify_container_sync()` to call `run_sync()` for each project
+- [x] Update all tests to match new API-based implementation
+
 ### Phase 3: Sync Command Dual Mode
 
 **3.1 Update `bm sync` Command**
@@ -207,15 +222,36 @@ This spec affects:
 - [ ] Handle errors gracefully, continue on failure
 - [ ] Show sync progress and status
 
-### Phase 4: Remove Duplicate Commands
-
-**4.1 Delete `bm cloud project` Commands**
-- [ ] Remove `bm cloud project list` (use `bm project list`)
-- [ ] Remove `bm cloud project add` (use `bm project add`)
-- [ ] Update `core_commands.py` to remove project_app subcommands
-- [ ] Keep only: `login`, `logout`, `status`, `setup`, `mount`, `unmount`
-
-**4.2 Update Documentation**
+### Phase 4: Remove Duplicate Commands & Cloud Mode Auth ✅
+
+**4.0 Cloud Mode Authentication** ✅
+- [x] Update `async_client.py` to support dual auth sources
+- [x] FastMCP context auth (cloud service mode) via `inject_auth_header()`
+- [x] JWT token file auth (CLI cloud mode) via `CLIAuth.get_valid_token()`
+- [x] Automatic token refresh for CLI cloud mode
+- [x] Remove `BASIC_MEMORY_PROXY_URL` environment variable dependency
+- [x] Simplify to use only `config.cloud_mode` + `config.cloud_host`
+
+**4.1 Delete `bm cloud project` Commands** ✅
+- [x] Remove `bm cloud project list` (use `bm project list`)
+- [x] Remove `bm cloud project add` (use `bm project add`)
+- [x] Update `core_commands.py` to remove project_app subcommands
+- [x] Keep only: `login`, `logout`, `status`, `setup`, `mount`, `unmount`, bisync commands
+- [x] Remove unused imports (Table, generate_permalink, os)
+- [x] Clean up environment variable references in login/logout
+
+**4.2 CLI Command Cloud Mode Integration** ✅
+- [x] Add runtime `cloud_mode_enabled` checks to all CLI commands
+- [x] Update `list_projects()` to conditionally authenticate based on cloud mode
+- [x] Update `remove_project()` to conditionally authenticate based on cloud mode
+- [x] Update `run_sync()` to conditionally authenticate based on cloud mode
+- [x] Update `get_project_info()` to conditionally authenticate based on cloud mode
+- [x] Update `run_status()` to conditionally authenticate based on cloud mode
+- [x] Remove auth from `set_default_project()` (local-only command, no cloud version)
+- [x] Create CLI integration tests (`test-int/cli/`) to validate both local and cloud modes
+- [x] Replace mock-heavy CLI tests with integration tests (deleted 5 mock test files)
+
+**4.3 Update Documentation**
 - [ ] Update `cloud-cli.md` with cloud mode toggle workflow
 - [ ] Document `bm cloud login` → use normal commands
 - [ ] Add examples of cloud mode usage
@@ -389,10 +425,13 @@ Bidirectional sync via rclone bisync
    # Syncs ALL project subdirectories bidirectionally
    ```
 
-6. **Notify cloud to refresh**
+6. **Notify cloud to refresh** (commit d48b1dc)
    ```python
-   # POST /proxy/sync (via async_client)
-   # Cloud sync service updates database from /app/data/
+   # After rclone bisync completes, sync each project's database
+   for project in cloud_projects:
+       # POST /{project}/project/sync (via async_client)
+       # Triggers background sync for this project
+       await run_sync(project=project_name)
    ```
 
 ### Key Changes

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

@@ -26,7 +26,10 @@ def get_cloud_config() -> tuple[str, str, str]:
 
 
 async def get_authenticated_headers() -> dict[str, str]:
-    """Get authentication headers with JWT token."""
+    """
+    Get authentication headers with JWT token.
+    handles jwt refresh if needed.
+    """
     client_id, domain, _ = get_cloud_config()
     auth = CLIAuth(client_id=client_id, authkit_domain=domain)
     token = await auth.get_valid_token()

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

@@ -1,14 +1,12 @@
 """Core cloud commands for Basic Memory CLI."""
 
 import asyncio
-import os
 from pathlib import Path
 from typing import Optional
 
 import httpx
 import typer
 from rich.console import Console
-from rich.table import Table
 
 from basic_memory.cli.app import cloud_app
 from basic_memory.cli.auth import CLIAuth
@@ -34,7 +32,6 @@
 from basic_memory.cli.commands.cloud.rclone_config import MOUNT_PROFILES
 from basic_memory.cli.commands.cloud.bisync_commands import BISYNC_PROFILES
 from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
-from basic_memory.utils import generate_permalink
 
 console = Console()
 
@@ -58,9 +55,6 @@ async def _login():
         config.cloud_mode = True
         config_manager.save_config(config)
 
-        # Set environment variable for current session
-        os.environ["BASIC_MEMORY_PROXY_URL"] = host_url
-
         console.print("[green]✓ Cloud mode enabled[/green]")
         console.print(f"[dim]All CLI commands now work against {host_url}[/dim]")
 
@@ -77,127 +71,10 @@ def logout():
     config.cloud_mode = False
     config_manager.save_config(config)
 
-    # Clear environment variable
-    os.environ.pop("BASIC_MEMORY_PROXY_URL", None)
-
     console.print("[green]✓ Cloud mode disabled[/green]")
     console.print("[dim]All CLI commands now work locally[/dim]")
 
 
-# Project commands
-
-project_app = typer.Typer(help="Manage Basic Memory Cloud Projects")
-cloud_app.add_typer(project_app, name="project")
-
-
-@project_app.command("list")
-def list_projects() -> None:
-    """List projects on the cloud instance."""
-
-    try:
-        # Get cloud configuration
-        _, _, host_url = get_cloud_config()
-        host_url = host_url.rstrip("/")
-
-        console.print(f"[blue]Fetching projects from {host_url}...[/blue]")
-
-        # Make API request to list projects
-        response = asyncio.run(
-            make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
-        )
-
-        projects_data = response.json()
-
-        if not projects_data.get("projects"):
-            console.print("[yellow]No projects found on the cloud instance.[/yellow]")
-            return
-
-        # Create table for display
-        table = Table(
-            title="Cloud Projects", show_header=True, header_style="bold blue", min_width=60
-        )
-        table.add_column("Name", style="green", min_width=20)
-        table.add_column("Path", style="dim", min_width=30)
-
-        for project in projects_data["projects"]:
-            # Format the path for display
-            path = project.get("path", "")
-            if path.startswith("/"):
-                path = f"~{path}" if path.startswith(str(Path.home())) else path
-
-            table.add_row(
-                project.get("name", "unnamed"),
-                path,
-            )
-
-        console.print(table)
-        console.print(f"\n[green]Found {len(projects_data['projects'])} project(s)[/green]")
-
-    except CloudAPIError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
-    except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
-        raise typer.Exit(1)
-
-
-@project_app.command("add")
-def add_project(
-    name: str = typer.Argument(..., help="Name of the project to add"),
-    set_default: bool = typer.Option(False, "--default", "-d", help="Set as default project"),
-) -> None:
-    """Create a new project on the cloud instance."""
-
-    # Get cloud configuration
-    _, _, host_url = get_cloud_config()
-    host_url = host_url.rstrip("/")
-
-    # Prepare headers
-    headers = {"Content-Type": "application/json"}
-
-    project_path = generate_permalink(name)
-    # Prepare project data
-    project_data = {
-        "name": name,
-        "path": project_path,
-        "set_default": set_default,
-    }
-
-    console.print(project_data)
-
-    try:
-        console.print(f"[blue]Creating project '{name}' on {host_url}...[/blue]")
-
-        # Make API request to create project
-        response = asyncio.run(
-            make_api_request(
-                method="POST",
-                url=f"{host_url}/proxy/projects/projects",
-                headers=headers,
-                json_data=project_data,
-            )
-        )
-
-        result = response.json()
-
-        console.print(f"[green]Project '{name}' created successfully![/green]")
-
-        # Display project details
-        if "project" in result:
-            project = result["project"]
-            console.print(f"  Name: {project.get('name', name)}")
-            console.print(f"  Path: {project.get('path', 'unknown')}")
-            if project.get("id"):
-                console.print(f"  ID: {project['id']}")
-
-    except CloudAPIError as e:
-        console.print(f"[red]Error creating project: {e}[/red]")
-        raise typer.Exit(1)
-    except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
-        raise typer.Exit(1)
-
-
 @cloud_app.command("upload")
 def upload_files(
     project: str = typer.Argument(..., help="Project name to upload to"),

src/basic_memory/cli/commands/command_utils.py

@@ -4,11 +4,15 @@
 
 from mcp.server.fastmcp.exceptions import ToolError
 import typer
+
 from rich.console import Console
+
+from basic_memory.cli.commands.cloud import get_authenticated_headers
 from basic_memory.mcp.async_client import client
 
-from basic_memory.mcp.tools.utils import call_post
+from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_context import get_active_project
+from basic_memory.schemas import ProjectInfoResponse
 
 console = Console()
 
@@ -17,10 +21,40 @@ async def run_sync(project: Optional[str] = None):
     """Run sync operation via API endpoint."""
 
     try:
-        project_item = await get_active_project(client, project, None)
-        response = await call_post(client, f"{project_item.project_url}/project/sync")
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = await get_authenticated_headers()
+
+        project_item = await get_active_project(client, project, None, headers=auth_headers)
+        response = await call_post(
+            client, f"{project_item.project_url}/project/sync", headers=auth_headers
+        )
         data = response.json()
         console.print(f"[green]✓ {data['message']}[/green]")
     except (ToolError, ValueError) as e:
         console.print(f"[red]✗ Sync failed: {e}[/red]")
         raise typer.Exit(1)
+
+
+async def get_project_info(project: str):
+    """Run sync operation via API endpoint."""
+
+    try:
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = await get_authenticated_headers()
+
+        project_item = await get_active_project(client, project, None, headers=auth_headers)
+        response = await call_get(
+            client, f"{project_item.project_url}/project/info", headers=auth_headers
+        )
+        return ProjectInfoResponse.model_validate(response.json())
+    except (ToolError, ValueError) as e:
+        console.print(f"[red]✗ Sync failed: {e}[/red]")
+        raise typer.Exit(1)