### Clone and Install Dependencies

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Initial setup commands to clone the repository and install backend and frontend dependencies.

```bash
git clone https://github.com/keithvassallomt/icloudbridge.git
cd icloudbridge
```

```bash
# Install backend dependencies
just install

# Install frontend dependencies
npm --prefix frontend install
```

--------------------------------

### Install iCloudBridge LaunchAgent

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Installs the iCloudBridge LaunchAgent for automatic startup. Optionally specify a port and enable starting on boot.

```bash
icloudbridge service install --port 8000 --start-on-boot
```

--------------------------------

### Install Dependencies

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Run this command to install all required project dependencies.

```bash
npm install
```

--------------------------------

### Install Development Prerequisites

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Installs necessary tools for development, including Python, Node.js, Ruby, and Just. Poetry is installed via pipx.

```bash
brew install python3 node just ruby
pipx install poetry
just install
```

--------------------------------

### Run Development Environment

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Commands to start the backend and frontend development servers.

```bash
just dev
```

```bash
npm --prefix frontend run dev
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Installs the Xcode Command Line Tools, which are required for development on macOS.

```bash
xcode-select --install
```

--------------------------------

### Launch icloudbridge server

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Commands to start the bundled FastAPI backend and WebUI.

```bash
icloudbridge serve --reload
icloudbridge serve --host 0.0.0.0 --port 9000
icloudbridge serve --background
```

--------------------------------

### Start Development Server

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Launches the local development server at http://localhost:3000 with hot module replacement.

```bash
npm run dev
```

--------------------------------

### Environment Configuration

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Example content for the .env file to configure API and WebSocket URLs.

```env
# API base URL (default: /api via proxy)
VITE_API_BASE_URL=http://localhost:8000/api

# WebSocket URL (default: ws://localhost:8000/api/ws via proxy)
VITE_WS_URL=ws://localhost:8000/api/ws
```

--------------------------------

### Start iCloudBridge Server

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Commands to launch the FastAPI backend server with various operational modes.

```bash
# Start development server with hot reload
icloudbridge serve --reload

# Start on custom host/port
icloudbridge serve --host 0.0.0.0 --port 9000

# Run in background (daemon mode)
icloudbridge serve --background
```

--------------------------------

### Get Version Information

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns version details for the application and the underlying Python runtime.

```bash
curl http://localhost:8000/api/version
# Response: {"version": "0.2.3", "python_version": "3.11.5"}
```

--------------------------------

### List Apple Reminders Lists

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all available Apple Reminders lists. No setup is required.

```bash
icloudbridge reminders list
```

--------------------------------

### Python WebSocket Client for Real-time Updates

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Establish a WebSocket connection using Python to receive real-time data. This example demonstrates subscribing to services and handling sync progress messages. Requires the 'websockets' and 'asyncio' libraries.

```python
# Python WebSocket client example
import asyncio
import websockets
import json

async def connect():
    async with websockets.connect('ws://localhost:8000/api/ws') as ws:
        # Subscribe to all services
        await ws.send(json.dumps({'type': 'subscribe', 'service': 'notes'}))
        await ws.send(json.dumps({'type': 'subscribe', 'service': 'reminders'}))

        async for message in ws:
            data = json.loads(message)
            if data['type'] == 'sync_progress':
                print(f"Sync progress: {data['data']['progress']}%")
            elif data['type'] == 'pong':
                print("Connection alive")

asyncio.run(connect())
```

--------------------------------

### Get Current Configuration

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves current settings without exposing sensitive credentials.

```bash
curl http://localhost:8000/api/config
# Response:
# {
#   "data_dir": "~/.icloudbridge",
#   "notes_enabled": true,
#   "reminders_enabled": true,
#   "passwords_enabled": false,
#   "photos_enabled": true,
#   "notes_remote_folder": "/Users/me/Nextcloud/Notes",
#   "reminders_caldav_url": "https://cloud.example.com/remote.php/dav",
#   "reminders_caldav_username": "user@example.com",
#   ...
# }
```

--------------------------------

### GET /api/version

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns version details for iCloudBridge and the Python runtime.

```APIDOC
## GET /api/version

### Description
Returns version details for iCloudBridge and the Python runtime.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **version** (string) - iCloudBridge version
- **python_version** (string) - Python runtime version
```

--------------------------------

### Get All Notes Folders

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns a mapping of folders from both Apple Notes and Markdown sources with existence indicators.

```bash
curl http://localhost:8000/api/notes/folders/all
# Response:
# {
#   "folders": {
#     "Work": {"apple": true, "markdown": true},
#     "Work/Projects": {"apple": true, "markdown": false},
#     "Personal": {"apple": true, "markdown": true},
#     "Configs": {"apple": false, "markdown": true}
#   }
# }
```

--------------------------------

### GET /api/reminders/caldav-calendars

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all calendars available on the configured CalDAV server.

```APIDOC
## GET /api/reminders/caldav-calendars

### Description
Lists all calendars available on the configured CalDAV server.

### Method
GET

### Endpoint
/api/reminders/caldav-calendars
```

--------------------------------

### Manage iCloudBridge Service

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Provides commands to start, stop, or restart the iCloudBridge LaunchAgent service.

```bash
icloudbridge service start
```

```bash
icloudbridge service stop
```

```bash
icloudbridge service restart
```

--------------------------------

### GET /api/notes/history

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns sync history with pagination.

```APIDOC
## GET /api/notes/history

### Description
Returns sync history with pagination.

### Method
GET

### Endpoint
/api/notes/history

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of records to return
- **offset** (integer) - Optional - Number of records to skip
```

--------------------------------

### Get Overall Sync Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves the synchronization status for all configured services.

```bash
curl http://localhost:8000/api/status
# Response includes notes, reminders, passwords, photos status with sync_count, last_sync, and enabled flags
```

--------------------------------

### GET /api/notes/folders

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all Apple Notes folders with note counts.

```APIDOC
## GET /api/notes/folders

### Description
Lists all Apple Notes folders with note counts.

### Method
GET

### Endpoint
/api/notes/folders
```

--------------------------------

### GET /api/reminders/status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns sync status including CalDAV configuration.

```APIDOC
## GET /api/reminders/status

### Description
Returns sync status including CalDAV configuration and password availability.

### Method
GET

### Endpoint
/api/reminders/status
```

--------------------------------

### GET /api/config

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves the current configuration without exposing sensitive data.

```APIDOC
## GET /api/config

### Description
Retrieves the current configuration without exposing sensitive data like passwords.

### Method
GET

### Endpoint
/api/config
```

--------------------------------

### Set Baseline for Photo Export

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Sets the baseline for future photo exports without performing an actual export. Useful for initial setup.

```bash
icloudbridge photos-export --set-baseline-only
```

--------------------------------

### GET /api/photos/status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves current photo sync statistics and library status.

```APIDOC
## GET /api/photos/status

### Description
Returns photo sync statistics including library items and pending imports.

### Method
GET

### Endpoint
/api/photos/status

### Response
#### Success Response (200)
- **enabled** (boolean) - Sync status.
- **library_items** (integer) - Total items in library.
- **last_imported** (integer) - Count of last imported items.
- **pending** (integer) - Count of pending items.
- **last_sync** (string) - Timestamp of last sync.
- **skipped_existing** (integer) - Count of skipped items.
- **sources** (array) - List of sync sources.
```

--------------------------------

### GET /api/schedules

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all sync schedules with optional filtering by service or enabled status.

```APIDOC
## GET /api/schedules

### Description
Lists all schedules with optional filtering by service or enabled status.

### Method
GET

### Endpoint
/api/schedules

### Parameters
#### Query Parameters
- **service** (string) - Optional - Filter by service name
- **enabled** (boolean) - Optional - Filter by enabled status

### Response
#### Success Response (200)
- **id** (integer) - Schedule ID
- **name** (string) - Schedule name
- **services** (array) - List of services
- **enabled** (boolean) - Enabled status
- **schedule_type** (string) - Type of schedule
- **interval_minutes** (integer) - Interval in minutes
- **next_run** (string) - Next scheduled run time
- **last_run** (string) - Last run time

#### Response Example
[
  {
    "id": 1,
    "name": "Hourly Notes Sync",
    "services": ["notes"],
    "enabled": true,
    "schedule_type": "interval",
    "interval_minutes": 60,
    "next_run": "2024-01-15T11:00:00",
    "last_run": "2024-01-15T10:00:00"
  }
]
```

--------------------------------

### Get Photos Export Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns the current configuration and statistics for photo exports, detailing export modes, folder locations, and total exported items.

```bash
curl http://localhost:8000/api/photos/export/status
```

--------------------------------

### Get Notes Sync History

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns sync history logs with support for pagination via limit and offset parameters.

```bash
curl "http://localhost:8000/api/notes/history?limit=10&offset=0"
```

--------------------------------

### CLI Command: serve

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Launches the bundled FastAPI backend and WebUI.

```APIDOC
## serve

### Description
Launch the bundled FastAPI backend + WebUI without using the menubar app. Helpful during development or when running on a server/VM.

### Parameters
#### Options
- **--host / -h** (string) - Optional - Interface to bind. Default: 127.0.0.1
- **--port / -p** (integer) - Optional - TCP port for HTTP/WebSocket traffic. Default: 8000
- **--reload** (flag) - Optional - Enable code auto-reload (development only).
- **--background / -d** (flag) - Optional - Detach and keep the server running in the background.
```

--------------------------------

### Manage configuration settings

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Commands to initialize or inspect the effective configuration file.

```bash
# Create ~/.icloudbridge/config.toml with sample sections
icloudbridge config --init

# Inspect settings currently in effect
icloudbridge config --show
```

--------------------------------

### Build for Production

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Commands to compile the project for production and preview the resulting build.

```bash
npm run build

npm run preview
```

--------------------------------

### GET /api/reminders/calendars

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all Apple Reminders lists with reminder counts.

```APIDOC
## GET /api/reminders/calendars

### Description
Lists all Apple Reminders lists with reminder counts.

### Method
GET

### Endpoint
/api/reminders/calendars
```

--------------------------------

### Display version information

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Shows the CLI, Python, and macOS build information.

```bash
icloudbridge version
```

--------------------------------

### GET /api/health

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns the current health status of the API server.

```APIDOC
## GET /api/health

### Description
Returns the current health status of the API server.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - Current health status
- **timestamp** (string) - ISO timestamp of the check
```

--------------------------------

### Build Configurations

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Various build commands for different deployment targets.

```bash
just build-debug
```

```bash
just build
```

```bash
just release
```

```bash
just build-backend
```

--------------------------------

### Initialize Configuration File

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Initializes a default configuration file for iCloudBridge if one does not exist.

```bash
icloudbridge config --init
```

--------------------------------

### API Client Usage

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Demonstrates how to interact with the backend using the centralized API client.

```typescript
import apiClient from '@/lib/api-client';

// Example usage
const schedules = await apiClient.getSchedules();
await apiClient.syncNotes({ mode: 'bidirectional' });
```

--------------------------------

### Perform system health check

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Runs a readiness check for data directories, database presence, and configuration.

```bash
icloudbridge health
```

--------------------------------

### Add shadcn/ui Component

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Use the shadcn-ui CLI to add new UI components to the project.

```bash
npx shadcn-ui@latest add dialog
```

--------------------------------

### Import media with photos

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Imports media from watch folders into Apple Photos, with options for dry runs and source filtering.

```bash
icloudbridge photos --dry-run
icloudbridge photos --initial-scan
icloudbridge photos --source nextcloud --source screenshots
```

--------------------------------

### Print database file paths

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Displays the file paths for Notes, Reminders, and Passwords SQLite databases.

```bash
icloudbridge db-paths
```

--------------------------------

### Show Current Configuration

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Displays the current configuration settings of iCloudBridge.

```bash
icloudbridge config --show
```

--------------------------------

### GET /api/notes/status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns current sync status, last sync details, and total mappings for Notes.

```APIDOC
## GET /api/notes/status

### Description
Returns current sync status, last sync details, and total mappings.

### Method
GET

### Endpoint
/api/notes/status

### Response
#### Success Response (200)
- **enabled** (boolean) - Sync status
- **remote_folder** (string) - Path to remote folder
- **total_mappings** (integer) - Total number of mappings
- **last_sync** (object) - Details of the last sync operation
```

--------------------------------

### Project Directory Structure

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Overview of the frontend source code organization.

```text
frontend/
├── src/
│   ├── components/
│   │   ├── Layout.tsx          # Main layout with sidebar
│   │   └── ui/                 # shadcn/ui components
│   ├── pages/
│   │   ├── Dashboard.tsx       # Status overview
│   │   ├── Notes.tsx           # Notes sync
│   │   ├── Reminders.tsx       # Reminders sync
│   │   ├── Passwords.tsx       # Passwords sync
│   │   ├── Schedules.tsx       # Schedule management
│   │   └── Settings.tsx        # Configuration
│   ├── store/
│   │   ├── app-store.ts        # Global app state
│   │   ├── sync-store.ts       # Sync operations state
│   │   └── schedules-store.ts  # Schedules state
│   ├── hooks/
│   │   └── useWebSocket.ts     # WebSocket hook
│   ├── lib/
│   │   ├── api-client.ts       # API client
│   │   └── utils.ts            # Utilities
│   ├── types/
│   │   └── api.ts              # TypeScript types
│   ├── App.tsx                 # Root component
│   ├── main.tsx                # Entry point
│   └── index.css               # Global styles
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.js
```

--------------------------------

### Sync Photos

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Syncs photos from configured sources. This command initiates the actual import and export process.

```bash
icloudbridge photos
```

--------------------------------

### Get Reminders Sync Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Returns sync status for Reminders, including CalDAV configuration and password availability.

```bash
curl http://localhost:8000/api/reminders/status
```

--------------------------------

### Reset Configuration

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a complete reset by deleting databases, clearing credentials, and removing configuration files.

```bash
curl -X POST http://localhost:8000/api/config/reset
# Response: {"status": "success", "message": "Configuration has been completely reset..."}
```

--------------------------------

### Run Code Quality Checks

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Commands to lint, format, and test the codebase.

```bash
# Run linter
just lint

# Auto-format code
just format

# Run tests
just test
```

--------------------------------

### Get Notes Sync Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves the current sync status, last sync details, and total mappings for Apple Notes.

```bash
curl http://localhost:8000/api/notes/status
```

--------------------------------

### Sync Photos (Dry Run)

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a dry run of the photos sync, showing what would be imported or exported without making changes.

```bash
icloudbridge photos --dry-run
```

--------------------------------

### Create Interval-Based Schedule

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Create a new schedule that runs at a defined interval in minutes. Ensure the Content-Type header is set to application/json.

```bash
# Interval-based schedule
curl -X POST http://localhost:8000/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Sync",
    "services": ["notes", "reminders"],
    "schedule_type": "interval",
    "interval_minutes": 60,
    "enabled": true
  }'
```

--------------------------------

### Service Management Commands

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Commands to manage the macOS LaunchAgent wrapper for the iCloudBridge API server.

```APIDOC
## service install

### Description
Installs the macOS LaunchAgent wrapper for the API server.

### Parameters
#### Query Parameters
- **--port** (number) - Optional - API port exposed by the service.
- **--start-on-boot** (boolean) - Optional - Auto-start when logging in (default: true).

## service uninstall

### Description
Removes the LaunchAgent plist and unloads it from launchctl.

## service status

### Description
Reports whether the LaunchAgent is loaded/running and shows the PID.
```

--------------------------------

### Get Password Sync Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves the status of the password synchronization service, including enabled status, provider configuration, and counts of entries by source.

```bash
curl http://localhost:8000/api/passwords/status
```

--------------------------------

### Get Photos Sync Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves current statistics for photo synchronization, including library item counts, pending imports, and last sync times.

```bash
curl http://localhost:8000/api/photos/status
```

--------------------------------

### Import Photos Sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Imports photos from configured watch folders into Apple Photos.

```bash
# Sync all sources
curl -X POST http://localhost:8000/api/photos/sync \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'
```

```bash
# Sync specific sources with initial scan
curl -X POST http://localhost:8000/api/photos/sync \
  -H "Content-Type: application/json" \
  -d '{
    "sources": ["nextcloud", "screenshots"],
    "dry_run": true,
    "initial_scan": false
  }'
```

--------------------------------

### POST /api/photos/sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Imports photos from configured watch folders into Apple Photos.

```APIDOC
## POST /api/photos/sync

### Description
Imports photos from configured watch folders into Apple Photos.

### Method
POST

### Endpoint
/api/photos/sync

### Request Body
- **dry_run** (boolean) - Optional - Simulate sync
- **sources** (array) - Optional - List of source folders
- **initial_scan** (boolean) - Optional - Perform initial scan
```

--------------------------------

### Project Structure Overview

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Visual representation of the project directory layout.

```text
icloudbridge/
├── icloudbridge/          # Python backend source
│   ├── api/              # FastAPI routes
│   ├── services/         # Sync logic (notes, reminders, photos, passwords)
│   ├── models/           # Pydantic models
│   └── utils/            # Helpers and utilities
├── frontend/             # React frontend
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── pages/        # Page components
│   │   ├── hooks/        # Custom hooks
│   │   ├── lib/          # Utilities and API client
│   │   └── store/        # Zustand state management
│   └── public/           # Static assets
├── macos/                # macOS menubar app
│   └── MenubarApp/       # Swift menubar application
├── scripts/              # Build and automation scripts
├── docs/                 # User documentation
├── justfile              # Task runner configuration
└── pyproject.toml        # Python dependencies
```

--------------------------------

### Test Service Connections

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Verifies connectivity to external services like CalDAV or VaultWarden using stored credentials.

```bash
# Test CalDAV connection
curl -X POST "http://localhost:8000/api/config/test-connection?service=reminders"
# Response: {"success": true, "message": "Successfully connected to CalDAV server. Found 3 calendars.", "calendars": ["Personal", "Work", "Family"]}

# Test VaultWarden connection
curl -X POST "http://localhost:8000/api/config/test-connection?service=passwords"
# Response: {"success": true, "message": "Successfully connected to VaultWarden server."}
```

--------------------------------

### Initial Photos Scan

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs an initial scan of photo sources to build the internal database without importing any photos.

```bash
icloudbridge photos --initial-scan
```

--------------------------------

### CLI: Export Rich Notes as HTML

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Generate HTML snapshot files for rich notes during the sync process. This preserves the formatting of notes that contain rich text elements.

```bash
icloudbridge notes sync --rich-notes
```

--------------------------------

### List Schedules with Filtering

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieve a list of all configured schedules. Filtering can be applied by service name or enabled status.

```bash
curl "http://localhost:8000/api/schedules?service=notes&enabled=true"
# Response:
# [
#   {
#     "id": 1,
#     "name": "Hourly Notes Sync",
#     "services": ["notes"],
#     "enabled": true,
#     "schedule_type": "interval",
#     "interval_minutes": 60,
#     "next_run": "2024-01-15T11:00:00",
#     "last_run": "2024-01-15T10:00:00"
#   }
# ]
```

--------------------------------

### Update Configuration Settings

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Updates application settings and persists them to disk.

```bash
curl -X PUT http://localhost:8000/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "notes_enabled": true,
    "notes_remote_folder": "/Users/me/Nextcloud/Notes",
    "reminders_enabled": true,
    "reminders_caldav_url": "https://cloud.example.com/remote.php/dav",
    "reminders_caldav_username": "user@example.com",
    "reminders_caldav_password": "secret-password"
  }'
```

--------------------------------

### CLI: Notes Sync Dry Run

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Preview the changes that would be made during a Notes sync without actually applying them. Useful for verifying sync operations.

```bash
icloudbridge notes sync --dry-run
```

--------------------------------

### POST /api/schedules

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Creates a new sync schedule.

```APIDOC
## POST /api/schedules

### Description
Creates a new sync schedule.

### Method
POST

### Endpoint
/api/schedules

### Request Body
- **name** (string) - Required - Name of the schedule
- **services** (array) - Required - List of services
- **schedule_type** (string) - Required - Type (interval or datetime)
- **interval_minutes** (integer) - Optional - Required for interval type
- **cron_expression** (string) - Optional - Required for datetime type
- **enabled** (boolean) - Required - Enabled status
- **config_json** (object) - Optional - Additional configuration
```

--------------------------------

### Validate Configuration

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Checks the current configuration for validity and required fields.

```bash
curl http://localhost:8000/api/config/validate
# Response: {"valid": true, "errors": []}
# Or: {"valid": false, "errors": ["Notes remote folder does not exist", "CalDAV password is not stored"]}
```

--------------------------------

### Trigger Schedule Run Now

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Manually initiate the execution of a specific schedule immediately.

```bash
curl -X POST http://localhost:8000/api/schedules/1/run
# Response: {"status": "success", "message": "Schedule 1 triggered"}
```

--------------------------------

### PUT /api/config

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Updates configuration and saves to disk.

```APIDOC
## PUT /api/config

### Description
Updates configuration and saves to disk. Passwords are stored in the macOS Keychain.

### Method
PUT

### Endpoint
/api/config

### Request Body
- **notes_enabled** (boolean) - Optional
- **notes_remote_folder** (string) - Optional
- **reminders_enabled** (boolean) - Optional
- **reminders_caldav_url** (string) - Optional
- **reminders_caldav_username** (string) - Optional
- **reminders_caldav_password** (string) - Optional
```

--------------------------------

### Activate Poetry Shell

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Optional command to enter the Poetry virtual environment for debugging.

```bash
poetry shell
```

--------------------------------

### CLI: Full Notes Sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Perform a full bidirectional synchronization of Apple Notes with Markdown files. This is the default behavior when running the notes sync command.

```bash
icloudbridge notes sync
```

--------------------------------

### CLI Command: notes sync

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Performs bidirectional synchronization between Apple Notes and Markdown files.

```APIDOC
## notes sync

### Description
Bidirectional Notes ⇄ Markdown sync.

### Parameters
#### Options
- **--folder / -f** (string) - Optional - Restrict the run to a single Apple Notes folder / Markdown subfolder.
- **--mode / -m** (string) - Optional - Direction: bidirectional, import (Markdown → Apple Notes), or export (Apple Notes → Markdown). Default: bidirectional
- **--dry-run / -n** (flag) - Optional - Preview changes without writing anything.
- **--skip-deletions** (flag) - Optional - Never delete notes on either side.
- **--deletion-threshold** (integer) - Optional - Maximum deletions allowed before aborting. Default: 5
- **--rich-notes / --no-rich-notes** (flag) - Optional - When enabled, export read-only Rich Notes HTML snapshots.
- **--shortcut-push / --classic-push** (flag) - Optional - Force the Shortcut pipeline or fall back to the legacy AppleScript HTML push.
```

--------------------------------

### List CalDAV Calendars

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all calendars currently available on the configured CalDAV server.

```bash
curl http://localhost:8000/api/reminders/caldav-calendars
```

--------------------------------

### List Apple Notes folders

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Displays detected Apple Notes folders with their names and UUIDs.

```bash
icloudbridge notes list
```

--------------------------------

### List Photo Albums

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Fetches a list of all available albums within the Apple Photos library, including their names and item counts.

```bash
curl http://localhost:8000/api/photos/library/albums
```

--------------------------------

### Verify Code Signing

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Validates the application signature after a production build.

```bash
just verify-signing
```

--------------------------------

### POST /api/schedules/{id}/run

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Manually triggers a schedule to run immediately.

```APIDOC
## POST /api/schedules/{id}/run

### Description
Manually triggers a schedule to run immediately.

### Method
POST

### Endpoint
/api/schedules/{id}/run

### Parameters
#### Path Parameters
- **id** (integer) - Required - Schedule ID
```

--------------------------------

### CLI Command: reminders sync

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Synchronize Apple Reminders with CalDAV calendars.

```APIDOC
## reminders sync

### Description
Synchronize Apple Reminders with CalDAV calendars.

### Parameters
#### Options
- **--apple-calendar / -a** (string) - Optional - Manually select an Apple Reminders list.
- **--caldav-calendar / -c** (string) - Optional - CalDAV calendar to pair with --apple-calendar.
- **--auto / --no-auto** (flag) - Optional - Force auto-discovery on/off.
- **--dry-run / -n** (flag) - Optional - Preview changes without modifying either side.
- **--skip-deletions** (flag) - Optional - Never delete reminders.
- **--deletion-threshold** (integer) - Optional - Abort if more than N deletions would occur. Default: 5
```

--------------------------------

### WebSocket /api/ws

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Connect to WebSocket for real-time sync progress, log streaming, and notifications.

```APIDOC
## WS /api/ws

### Description
Connect to WebSocket for real-time sync progress, log streaming, and notifications.

### Endpoint
ws://localhost:8000/api/ws

### Message Types
- **subscribe** - Subscribe to a service
- **ping** - Keep connection alive
- **sync_progress** - Receive progress updates
- **log_entry** - Receive log entries
- **schedule_run** - Receive schedule run status
```

--------------------------------

### List Apple Notes Folders

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Retrieves a list of Apple Notes folders along with their respective note counts.

```bash
curl http://localhost:8000/api/notes/folders
# Response: {"folders": [{"name": "Personal", "uuid": "abc123", "note_count": 15}, {"name": "Work", "uuid": "def456", "note_count": 8}]}
```

--------------------------------

### Sync Specific Photo Sources

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Syncs photos only from the specified sources. Multiple --source flags can be used.

```bash
icloudbridge photos --source nextcloud --source screenshots
```

--------------------------------

### Synchronize Apple Notes

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Commands for bidirectional synchronization between Apple Notes and Markdown files.

```bash
icloudbridge notes sync                       # full sync
icloudbridge notes sync --dry-run             # preview
icloudbridge notes sync --mode export         # Apple → Markdown only
icloudbridge notes sync --folder "Work" --skip-deletions
icloudbridge notes sync --rich-notes --classic-push
```

--------------------------------

### Import Apple Password CSV

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Seeds the local password database using Apple's 'Export Passwords' CSV file. Records the import statistics.

```bash
curl -X POST http://localhost:8000/api/passwords/import/apple \
  -F "file=@/path/to/apple-passwords.csv"
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/README.md

Removes build directories and temporary files.

```bash
just clean
```

--------------------------------

### POST /api/config/test-connection

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Tests connectivity to CalDAV or VaultWarden services.

```APIDOC
## POST /api/config/test-connection

### Description
Tests connectivity to CalDAV or VaultWarden services using stored credentials.

### Method
POST

### Endpoint
/api/config/test-connection

### Parameters
#### Query Parameters
- **service** (string) - Required - The service to test (e.g., 'reminders', 'passwords')
```

--------------------------------

### CLI: Reminders Sync Dry Run

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Preview the changes that would occur during a Reminders sync without applying them. This is useful for verifying the intended synchronization actions.

```bash
icloudbridge reminders sync --dry-run
```

--------------------------------

### POST /api/notes/sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Triggers bidirectional synchronization between Apple Notes and Markdown files.

```APIDOC
## POST /api/notes/sync

### Description
Triggers bidirectional synchronization between Apple Notes and Markdown files.

### Method
POST

### Endpoint
/api/notes/sync

### Request Body
- **mode** (string) - Optional - Sync mode (e.g., "bidirectional", "export")
- **dry_run** (boolean) - Optional - If true, simulates the sync without making changes
- **folder** (string) - Optional - Specific folder to sync
- **skip_deletions** (boolean) - Optional - Whether to skip deletions
- **deletion_threshold** (integer) - Optional - Threshold for deletions
- **rich_notes_export** (boolean) - Optional - Enable rich notes export
- **use_shortcuts** (boolean) - Optional - Use shortcuts for sync

### Response
#### Success Response (200)
- **status** (string) - Status message
- **message** (string) - Details about sync results
- **duration_seconds** (number) - Time taken
- **stats** (object) - Sync statistics
- **log_id** (integer) - ID of the log entry
```

--------------------------------

### Sync Passwords (Full)

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a bidirectional synchronization of passwords between Apple Passwords and VaultWarden. Supports simulation mode and bulk operations.

```bash
curl -X POST http://localhost:8000/api/passwords/sync \
  -F "file=@/path/to/apple-passwords.csv" \
  -F "simulate=false" \
  -F "bulk=true"
```

--------------------------------

### Export Full Library or Specific Album

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Initiates a photo export. Can export the entire library or filter by album and date. Includes a dry run option to preview changes without actual export.

```bash
curl -X POST http://localhost:8000/api/photos/export \
  -H "Content-Type: application/json" \
  -d '{
    "full_library": true,
    "album_filter": "Vacation 2024",
    "since_date": "2024-01-01",
    "dry_run": true
  }'
```

--------------------------------

### Password Management Commands

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Commands for synchronizing, importing, exporting, and managing credentials for password providers.

```APIDOC
## passwords provider [SERVICE]

### Description
Show or set the active downstream service (bitwarden, vaultwarden, or nextcloud).

### Parameters
#### Path Parameters
- **SERVICE** (string) - Optional - The provider name (bitwarden, vaultwarden, nextcloud).

## passwords import-apple [CSV]

### Description
Seed the database using Apple’s “Export Passwords…” CSV.

### Parameters
#### Path Parameters
- **CSV** (string) - Required - Path to the Apple export CSV file.

## passwords export-bitwarden

### Description
Build a Bitwarden/Vaultwarden-compatible CSV.

### Parameters
#### Query Parameters
- **--output, -o** (string) - Required - Destination file path.
- **--apple-csv** (string) - Required - The original Apple export used to map UUIDs.

## passwords sync

### Description
Perform end-to-end synchronization between Apple and the configured provider.

### Parameters
#### Query Parameters
- **--apple-csv** (string) - Required - Fresh Apple “Export Passwords…” CSV.
- **--output, -o** (string) - Optional - Path for the Apple-import CSV.
- **--bulk** (flag) - Optional - Enable provider-specific bulk APIs.
```

--------------------------------

### Full Password Sync with VaultWarden

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a full synchronization of passwords with VaultWarden. Requires the path to an Apple Passwords CSV and uses bulk import.

```bash
icloudbridge passwords sync --apple-csv /path/to/apple-passwords.csv --bulk
```

--------------------------------

### WebSocket Hook Integration

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/frontend/README.md

Utilize the useWebSocket hook to handle real-time sync progress and log entries.

```typescript
import { useWebSocket } from '@/hooks/useWebSocket';

const { isConnected } = useWebSocket({
  onSyncProgress: (service, data) => {
    // Handle sync progress
  },
  onLogEntry: (service, data) => {
    // Handle log entry
  },
});
```

--------------------------------

### CLI: Sync Specific Reminders Calendars

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Synchronize specific Apple Reminders calendars with corresponding CalDAV calendars. Use --apple-calendar to specify the source and --caldav-calendar for the destination.

```bash
icloudbridge reminders sync --apple-calendar "Reminders" --caldav-calendar "tasks"
```

--------------------------------

### Check Notes sync status

Source: https://github.com/keithvassallomt/icloudbridge/blob/main/docs/USAGE.md

Displays total synced entries, Markdown path, and database location.

```bash
icloudbridge notes status
```

--------------------------------

### Store Bitwarden Credentials

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Stores the Bitwarden (or VaultWarden) credentials in the system's keychain for authentication.

```bash
icloudbridge passwords set-bitwarden-credentials
```

--------------------------------

### POST /api/reminders/sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Synchronizes Apple Reminders with CalDAV calendars.

```APIDOC
## POST /api/reminders/sync

### Description
Synchronizes Apple Reminders with CalDAV calendars.

### Method
POST

### Endpoint
/api/reminders/sync

### Request Body
- **auto** (boolean) - Optional - Enable auto-sync
- **dry_run** (boolean) - Optional - Simulate sync
- **apple_calendar** (string) - Optional - Name of Apple calendar
- **caldav_calendar** (string) - Optional - Name of CalDAV calendar
- **skip_deletions** (boolean) - Optional - Skip deletions
- **deletion_threshold** (integer) - Optional - Deletion threshold
```

--------------------------------

### Import Apple Passwords CSV

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Imports Apple Passwords from a CSV file into the iCloudBridge database. Provide the path to the CSV file.

```bash
icloudbridge passwords import-apple /path/to/apple-passwords.csv
```

--------------------------------

### POST /api/passwords/sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a bidirectional sync between Apple Passwords and VaultWarden.

```APIDOC
## POST /api/passwords/sync

### Description
Bidirectional sync: pushes Apple Passwords to VaultWarden and pulls new entries back.

### Method
POST

### Endpoint
/api/passwords/sync

### Request Body
- **file** (file) - Required - Apple passwords CSV file.
- **simulate** (boolean) - Optional - Whether to simulate the sync.
- **bulk** (boolean) - Optional - Whether to perform a bulk sync.

### Response
#### Success Response (200)
- **status** (string) - Operation status.
- **stats** (object) - Sync statistics for push and pull operations.
- **download** (object) - Contains download token and metadata for the generated CSV.
```

--------------------------------

### Check Service Status

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Checks the status of the iCloudBridge LaunchAgent service.

```bash
icloudbridge service status
```

--------------------------------

### JavaScript WebSocket Client for Real-time Updates

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Connect to the WebSocket endpoint to receive real-time notifications on sync progress, logs, and schedule events. Requires a browser or Node.js environment with WebSocket support. Subscribe to specific services to receive relevant updates.

```javascript
// JavaScript WebSocket client example
const ws = new WebSocket('ws://localhost:8000/api/ws');

ws.onopen = () => {
  console.log('Connected to iCloudBridge');

  // Subscribe to notes service updates
  ws.send(JSON.stringify({ type: 'subscribe', service: 'notes' }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case 'sync_progress':
      console.log(`${message.service}: ${message.data.progress}% - ${message.data.message}`);
      break;
    case 'log_entry':
      console.log(`[${message.data.level}] ${message.data.message}`);
      break;
    case 'schedule_run':
      console.log(`Schedule ${message.data.schedule_name}: ${message.data.status}`);
      break;
    case 'error':
      console.error(`Error: ${message.data.error_message}`);
      break;
  }
};

// Keep connection alive with ping
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 30000);
```

--------------------------------

### Export Photos

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Exports photos from the iCloudBridge database to a local folder. This command initiates the actual export.

```bash
icloudbridge photos-export
```

--------------------------------

### POST /api/notes/reset

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Clears all note mappings and sync history.

```APIDOC
## POST /api/notes/reset

### Description
Clears all note mappings and sync history. Notes are not deleted.

### Method
POST

### Endpoint
/api/notes/reset
```

--------------------------------

### Reset Passwords Database

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Use this POST request to clear all stored passwords, history, and keychain credentials. This action is irreversible.

```bash
curl -X POST http://localhost:8000/api/passwords/reset
# Response: {"status": "success", "message": "Passwords database, history, and keychain credentials reset successfully."}
```

--------------------------------

### Export Photos (Dry Run)

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Performs a dry run of the photos export process, showing which photos would be exported without actually exporting them.

```bash
icloudbridge photos-export --dry-run
```

--------------------------------

### Import Passwords from VaultWarden

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Pulls new entries from VaultWarden and prepares an Apple CSV for import. Supports simulation mode.

```bash
curl -X POST "http://localhost:8000/api/passwords/sync/import?simulate=false"
```

--------------------------------

### List Apple Reminders Calendars

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Lists all available Apple Reminders lists along with their respective reminder counts.

```bash
curl http://localhost:8000/api/reminders/calendars
```

--------------------------------

### Reset Notes Database

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Clears all note mappings and sync history without deleting the actual notes.

```bash
curl -X POST http://localhost:8000/api/notes/reset
```

--------------------------------

### Uninstall iCloudBridge LaunchAgent

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Uninstalls the iCloudBridge LaunchAgent, stopping automatic startup.

```bash
icloudbridge service uninstall
```

--------------------------------

### Export Passwords for Bitwarden

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Exports passwords in a format suitable for importing into Bitwarden. Specify the output CSV file path.

```bash
icloudbridge passwords export-bitwarden --output /path/to/bitwarden-import.csv
```

--------------------------------

### Create Cron-Based Schedule

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Create a new schedule using a cron expression for precise timing. A config_json field can include additional options like dry_run.

```bash
# Cron-based schedule
curl -X POST http://localhost:8000/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily 9am Sync",
    "services": ["photos"],
    "schedule_type": "datetime",
    "cron_expression": "0 9 * * *",
    "enabled": true,
    "config_json": {"dry_run": false}
  }'
```

--------------------------------

### CLI: Auto Reminders Sync

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Perform an automatic synchronization of all Apple Reminders with CalDAV servers. This command simplifies the sync process by handling default configurations.

```bash
icloudbridge reminders sync --auto
```

--------------------------------

### Export Entire Photo Library

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Exports all photos from the iCloudBridge library. Use with caution as this can be a large operation.

```bash
icloudbridge photos-export --full-library
```

--------------------------------

### POST /api/photos/export

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Exports photos from Apple Photos to a local folder for Nextcloud sync.

```APIDOC
## POST /api/photos/export

### Description
Exports photos from Apple Photos to a local folder for Nextcloud sync.

### Method
POST

### Endpoint
/api/photos/export

### Request Body
- **dry_run** (boolean) - Optional - Simulate export
```

--------------------------------

### Set Photos Export Baseline

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Updates the export baseline to the current time. Photos with dates prior to this baseline will not be exported unless a full library export is specified.

```bash
curl -X POST http://localhost:8000/api/photos/export/set-baseline
```

--------------------------------

### Export Photos Since Date

Source: https://context7.com/keithvassallomt/icloudbridge/llms.txt

Exports photos that were added or modified since a specific date. The date should be in YYYY-MM-DD format.

```bash
icloudbridge photos-export --since 2024-01-01
```