basicmachines-co-basic-memory/docs/cloud-cli.md

# Basic Memory Cloud CLI Guide

The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using a **cloud mode toggle**. When cloud mode is enabled, all your regular `bm` commands work transparently with the cloud instead of locally.

## Overview

The cloud CLI enables you to:
- **Toggle cloud mode** with `bm cloud login` / `bm cloud logout`
- **Use regular commands in cloud mode**: `bm project`, `bm sync`, `bm tool` all work with cloud
- **Bidirectional sync** with rclone bisync (recommended for most users)
- **Direct file access** via rclone mount (alternative workflow)
- **Integrity verification** with `bm cloud check`
- **Automatic project creation** from local directories

## Prerequisites

Before using Basic Memory Cloud, you need:

- **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
- **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up

If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.

## The Cloud Mode Paradigm

Basic Memory Cloud follows the **Dropbox/iCloud model** - a single cloud space containing all your projects, not per-project connections.

**How it works:**
- One login per machine: `bm cloud login`
- One sync directory: `~/basic-memory-cloud-sync/` (all projects)
- Projects are folders within your cloud space
- All regular commands work in cloud mode

**Why this model:**
- ✅ Single set of credentials (not N per project)
- ✅ One rclone process (not N processes)
- ✅ Familiar pattern (like Dropbox)
- ✅ Simple operations (setup once, sync anytime)
- ✅ Natural scaling (add projects = add folders)

## Quick Start

### 1. Enable Cloud Mode

Authenticate and enable cloud mode for all commands:

```bash
bm cloud login
```

This command will:
1. Open your browser to the Basic Memory Cloud authentication page
2. Prompt you to authorize the CLI application
3. Store your authentication token locally
4. **Enable cloud mode** - all CLI commands now work against cloud

### 2. Set Up Sync

Set up bidirectional file synchronization:

```bash
bm cloud setup
```

This will:
1. Install rclone automatically (if needed)
2. Configure sync credentials
3. Create `~/basic-memory-cloud-sync/` directory
4. Establish initial sync baseline

**Alternative:** Use `bm cloud setup --mount` to set up mount instead of sync.

### 3. Verify Setup

Check that everything is working:

```bash
bm cloud status
```

You should see:
- `Mode: Cloud (enabled)`
- `Cloud instance is healthy`
- Bisync status showing `✓ Initialized`

### 4. Start Using Cloud

Now all your regular commands work with the cloud:

```bash
# List cloud projects
bm project list

# Create cloud project
bm project add "my-research"

# Use MCP tools on cloud
bm tool write-note --title "Hello" --folder "my-research" --content "Test"

# Sync with cloud
bm sync

# Watch mode for continuous sync
bm sync --watch
```

### 5. Disable Cloud Mode

Return to local mode:

```bash
bm cloud logout
```

All commands now work locally again.

## Working with Cloud Projects

**Important:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).

### Listing Projects

View all projects (cloud projects when cloud mode is enabled):

```bash
# In cloud mode - lists cloud projects
bm project list

# In local mode - lists local projects
bm project list
```

### Creating Projects

Create a new project (creates on cloud when cloud mode is enabled):

```bash
# In cloud mode - creates cloud project
bm project add my-new-project

# Create and set as default
bm project add my-new-project --default
```

### Automatic Project Creation

**New in SPEC-9:** Projects are automatically created when you create local directories!

```bash
# Create a local directory in your sync folder
mkdir ~/basic-memory-cloud-sync/new-project
echo "# Notes" > ~/basic-memory-cloud-sync/new-project/readme.md

# Sync - automatically creates cloud project
bm sync

# Verify - project now exists on cloud
bm project list
```

This Dropbox-like workflow means you don't need to manually coordinate projects between local and cloud.

## File Synchronization

### The `bm sync` Command (Cloud Mode Aware)

The `bm sync` command automatically adapts based on cloud mode:

**In local mode:**
```bash
bm sync              # Indexes local files into database
```

**In cloud mode:**
```bash
bm sync              # Runs bisync + indexes files
bm sync --watch      # Continuous sync every 60 seconds
bm sync --interval 30  # Custom interval
```

The same command works everywhere - no need to remember different commands for local vs cloud!

## Bidirectional Sync (bisync) - Recommended

Bidirectional sync is the **recommended approach** for most users. It provides:
- ✅ Offline access to all files
- ✅ Automatic bidirectional synchronization
- ✅ Conflict detection and resolution
- ✅ Works with any editor or tool
- ✅ Background watch mode

### Setup

Set up bisync (runs automatically if you used `bm cloud setup`):

```bash
bm cloud setup
```

Or set up with custom directory:

```bash
bm cloud setup --dir ~/my-sync-folder
```

### Running Sync

Use the cloud-aware `bm sync` command:

```bash
# Manual sync
bm sync

# Watch mode (continuous sync)
bm sync --watch

# Custom interval (30 seconds)
bm sync --watch --interval 30
```

### Bisync Profiles

Bisync supports three conflict resolution strategies with different safety levels:

| Profile | Conflict Resolution | Max Deletes | Use Case |
|---------|-------------------|-------------|----------|
| **balanced** | newer | 25 | Default, recommended for most users |
| **safe** | none | 10 | Keep both versions on conflict |
| **fast** | newer | 50 | Rapid iteration, higher delete tolerance |

**Profile Details:**

- **safe**:
  - Conflict resolution: `none` (creates `.conflict` files for both versions)
  - Max delete: 10 files per sync
  - Best for: Critical data where you want manual conflict resolution

- **balanced** (default):
  - Conflict resolution: `newer` (auto-resolve to most recent file)
  - Max delete: 25 files per sync
  - Best for: General use with automatic conflict handling

- **fast**:
  - Conflict resolution: `newer` (auto-resolve to most recent file)
  - Max delete: 50 files per sync
  - Best for: Rapid development iteration with less restrictive safety checks

**How to Select a Profile:**

The default profile (`balanced`) is used automatically with `bm sync`:

```bash
# Uses balanced profile (default)
bm sync
```

For advanced control, use `bm cloud bisync` with the `--profile` flag:

```bash
# Use safe mode
bm cloud bisync --profile safe

# Use fast mode
bm cloud bisync --profile fast

# Preview changes with specific profile
bm cloud bisync --profile safe --dry-run
```

**Check Available Profiles:**

```bash
bm cloud status
```

This shows all available profiles with their settings.

**Current Limitations:**

- Profiles are hardcoded and cannot be customized
- No config file option to change default profile
- Profile settings (max_delete, conflict_resolve) cannot be modified without code changes
- Profile selection only available via `bm cloud bisync --profile` (advanced command)

### Establishing New Baseline

If you need to force a complete resync:

```bash
bm cloud bisync --resync
```

**Warning:** This overwrites the sync state. Use only when recovering from errors.

### Checking Sync Status

View current sync status:

```bash
bm cloud status
```

This shows:
- Cloud mode status
- Instance health
- Sync directory location
- Last sync time
- Available bisync profiles

### Verifying Sync Integrity

Check that local and cloud files match:

```bash
# Full integrity check
bm cloud check

# Faster one-way check
bm cloud check --one-way
```

This uses `rclone check` to verify files match without transferring data.

### Working with Bisync

Create and edit files in `~/basic-memory-cloud-sync/`:

```bash
# Create a new note
echo "# My Research" > ~/basic-memory-cloud-sync/my-project/notes.md

# Edit with your favorite editor
code ~/basic-memory-cloud-sync/my-project/

# Sync changes to cloud
bm sync
```

In watch mode, changes sync automatically:

```bash
# Start watch mode
bm sync --watch

# Edit files - they sync automatically every 60 seconds
code ~/basic-memory-cloud-sync/my-project/
```

### Filter Configuration

Bisync uses `.bmignore` patterns from `~/.basic-memory/.bmignore`:

```bash
# View current ignore patterns
cat ~/.basic-memory/.bmignore

# Edit ignore patterns
code ~/.basic-memory/.bmignore
```

Example `.bmignore`:

```gitignore
# This file is used by 'bm cloud bisync' and file sync
# Patterns use standard gitignore-style syntax

# Hidden files (files starting with dot)
- .*

# Basic Memory internal files
- memory.db/**
- memory.db-shm/**
- memory.db-wal/**
- config.json/**

# Version control
- .git/**

# Python
- __pycache__/**
- *.pyc
- .venv/**

# Node.js
- node_modules/**
```

**Key points:**
- ✅ **Global configuration** - One ignore file for all projects
- ✅ **rclone filter syntax** - Patterns with `- ` prefix
- ✅ **Automatic creation** - Created with defaults on first use
- ✅ **Shared patterns** - Same patterns used by sync service

## NFS Mount (Direct Access) - Alternative

NFS mount provides direct file system access as an alternative to bisync. Use this if you prefer mounting files like a network drive.

### Setup

Set up mount instead of bisync:

```bash
bm cloud setup --mount
```

### Mounting Files

Mount your cloud files:

```bash
# Mount with default settings
bm cloud mount

# Mount with specific profile
bm cloud mount --profile fast
```

#### Mount Profiles

- **balanced** (default): Balanced caching for general use
- **streaming**: Optimized for large files
- **fast**: Minimal verification for rapid access

### Checking Mount Status

View current mount status:

```bash
bm cloud status --mount
```

### Unmounting Files

Unmount when done:

```bash
bm cloud unmount
```

### Working with Mounted Files

Once mounted, files appear at `~/basic-memory-cloud/`:

```bash
# List cloud files
ls ~/basic-memory-cloud/

# Edit with your favorite editor
code ~/basic-memory-cloud/my-project/

# Changes are immediately synced to cloud
echo "# Notes" > ~/basic-memory-cloud/my-project/readme.md
```

**Note:** Changes are written through to cloud immediately. There's no "sync" step needed.

## Instance Management

### Health Check

Check if your cloud instance is healthy:

```bash
bm cloud status
```

This shows:
- Cloud mode enabled/disabled
- Instance health status
- Instance version
- Sync or mount status

## Troubleshooting

### Authentication Issues

**Problem**: "Authentication failed" or "Invalid token"

**Solution**: Re-authenticate:

```bash
bm cloud logout
bm cloud login
```

### Subscription Issues

**Problem**: "Subscription Required" error when logging in

**Solution**: You need an active Basic Memory Cloud subscription to use cloud features.

1. Visit the subscribe URL shown in the error message
2. Sign up for a subscription
3. Once your subscription is active, run `bm cloud login` again

**Problem**: "Subscription Required" error for existing user

**Solution**: Your subscription may have expired or been cancelled.

1. Check your subscription status at [https://basicmemory.com/account](https://basicmemory.com/account)
2. Renew your subscription if needed
3. Run `bm cloud login` again

Note: Access is immediately restored when your subscription becomes active.

### Sync Issues

**Problem**: "Bisync not initialized"

**Solution**: Run setup or initialize with resync:

```bash
bm cloud setup
# or
bm cloud bisync --resync
```

**Problem**: "Too many deletes" error

**Solution**: Bisync detected many deletions (safety check). Review changes and use a higher delete limit profile or force resync:

```bash
bm cloud bisync --profile fast  # Higher delete limit
# or
bm cloud bisync --resync        # Force baseline
```

**Problem**: Conflicts detected

**Solution**: Bisync found files changed in both locations. Check sync directory for `.conflict` files:

```bash
ls ~/basic-memory-cloud-sync/**/*.conflict
```

Resolve conflicts manually, then sync again.

### Connection Issues

**Problem**: "Cannot connect to cloud instance"

**Solution**: Check cloud status:

```bash
bm cloud status
```

If instance is down, wait a few minutes and retry. If problem persists, contact support.

### Mount Issues

**Problem**: "Mount point is busy"

**Solution**: Unmount and remount:

```bash
bm cloud unmount
bm cloud mount
```

**Problem**: "Permission denied" when accessing mounted files

**Solution**: Check mount status and remount:

```bash
bm cloud status --mount
bm cloud unmount
bm cloud mount
```

## Security

- **Authentication**: OAuth 2.1 with PKCE flow
- **Tokens**: Stored securely in `~/.basic-memory/auth/token`
- **Transport**: All data encrypted in transit (HTTPS)
- **Credentials**: Scoped S3 credentials for sync/mount (read-write access to your tenant only)
- **Isolation**: Your data is isolated from other tenants
- **Ignore patterns**: Sensitive files (`.env`, credentials) automatically excluded

## Command Reference

### Cloud Mode Management

```bash
bm cloud login                   # Authenticate and enable cloud mode
bm cloud logout                  # Disable cloud mode
bm cloud status                  # Check cloud mode and sync status
bm cloud status --mount          # Check cloud mode and mount status
```

### Setup

```bash
bm cloud setup                   # Setup bisync (default, recommended)
bm cloud setup --mount           # Setup mount (alternative)
bm cloud setup --dir ~/sync      # Custom sync directory
```

### Project Management (Cloud Mode Aware)

When cloud mode is enabled, these commands work with cloud:

```bash
bm project list                  # List projects
bm project add <name>            # Create project
bm project add <name> --default  # Create and set as default
bm project rm <name>             # Delete project
bm project set-default <name>    # Set default project
```

### File Synchronization

```bash
bm sync                          # Sync files (local or cloud depending on mode)
bm sync --watch                  # Continuous sync (cloud mode only)
bm sync --interval 30            # Custom interval for watch mode

# Advanced bisync commands
bm cloud bisync                  # Run bisync manually
bm cloud bisync --profile safe   # Use specific profile
bm cloud bisync --dry-run        # Preview changes
bm cloud bisync --resync         # Force new baseline
bm cloud bisync --watch          # Continuous sync
bm cloud bisync --verbose        # Show detailed output

# Integrity verification
bm cloud check                   # Full integrity check
bm cloud check --one-way         # Faster one-way check
```

### Direct File Access (Mount)

```bash
bm cloud mount                   # Mount cloud files
bm cloud mount --profile fast    # Use specific profile
bm cloud unmount                 # Unmount files
```

## Summary

Basic Memory Cloud provides two workflows:

### Recommended: Bidirectional Sync (bisync)
1. `bm cloud login` - Authenticate once
2. `bm cloud setup` - Configure sync once
3. `bm sync` - Sync anytime (or use `--watch`)
4. Work in `~/basic-memory-cloud-sync/`
5. Changes sync bidirectionally

### Alternative: Direct Mount
1. `bm cloud login` - Authenticate once
2. `bm cloud setup --mount` - Configure mount once
3. `bm cloud mount` - Mount when needed
4. Work in `~/basic-memory-cloud/`
5. Changes write through immediately

Both approaches work seamlessly with cloud mode - all your regular `bm` commands work with either workflow!