> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Sync

> Continuously sync local folders, databases, and chat history to Nia — with optional end-to-end encryption.

Nia Sync is a standalone CLI daemon that continuously synchronizes your local data sources with Nia, enabling AI agents to search your personal knowledge base.

[Local Sync Demo](https://www.youtube.com/embed/vDOA1ealkp8)

> [!NOTE]
>
> **Privacy First**: Local folders are private to your account. They're searched separately from public repositories and documentation.

***

## Quick Install

> [!WARNING]
>
> **`nia-sync` is deprecated.** Local sync is now built into the main Nia CLI installed by `npx nia-wizard@latest`. If you previously installed `nia-sync` via `pip` or `uv`, uninstall it to avoid conflicts with the new `nia` command:
>
> ```bash theme={null}
> pip uninstall nia-sync   # or: uv pip uninstall nia-sync
> ```
>
> Then follow the [Installation guide](https://docs.trynia.ai/integrations/installation/overview.md) to set up the current CLI.

Follow the [Installation guide](https://docs.trynia.ai/integrations/installation/overview.md) to install the Nia CLI via `npx nia-wizard@latest`.

***

## Getting Started

**1. Login**

Authenticate with your Nia account:

```bash theme={null}
nia login
```

This opens your browser for secure OAuth authentication.

**2. Add a Source**

Add a local folder or database to sync:

```bash theme={null}
nia add ~/Documents/notes
```

The CLI auto-detects known database paths (iMessage, browser history, etc.).

**3. Start Syncing**

Start the sync daemon:

```bash theme={null}
nia
```

The daemon watches for file changes and syncs incrementally in real-time.

**4. Check Status**

View all synced sources:

```bash theme={null}
nia status
```

***

## CLI Commands

### Core Commands

| Command | Description |
| - | - |
| `nia` | Start sync daemon (watch mode by default) |
| `nia login` | Browser-based OAuth authentication |
| `nia logout` | Clear stored credentials |
| `nia status` | Show all configured sources with sync status |
| `nia status --json` | Output status as JSON for scripting |
| `nia once` | Run one-time sync then exit |
| `nia add <path>` | Add new source for sync |
| `nia link <ID> <path>` | Link cloud source to local path |
| `nia remove <ID>` | Remove source from sync |
| `nia upgrade` | Check and install updates |

### Search & Query

Search your indexed sources directly from the terminal:

```bash theme={null}
# Basic search with streaming AI response
nia search "meeting notes from last week"

# Search specific folders
nia search "project updates" --local-folder my-notes --local-folder work-docs

# Show source snippets alongside the answer
nia search "authentication code" --sources

# Raw text output (no markdown rendering)
nia search "api endpoints" --no-markdown

# JSON output for scripting
nia search "config values" --json --no-stream
```

| Flag | Description |
| - | - |
| `-l, --local-folder` | Limit search to specific folder(s). Accepts ID prefix or display name |
| `--sources` | Show source snippets used to generate the answer |
| `--markdown/--no-markdown` | Toggle rich Markdown rendering (default: on) |
| `--stream/--no-stream` | Toggle streaming response (default: on) |
| `-j, --json` | Output raw JSON for programmatic use |
| `-n, --limit` | Max source snippets to display |

### Monitoring & Debugging

| Command | Description |
| - | - |
| `nia info <ID>` | Show detailed info for a source (chunk count, last sync, errors) |
| `nia logs` | Show sync logs for all sources |
| `nia logs <ID>` | Show sync logs for a specific source |
| `nia logs --tail` | Continuously tail new logs |
| `nia logs --errors` | Only show error logs |
| `nia diff` | Dry-run: show what would sync without uploading |
| `nia diff <ID>` | Dry-run for a specific source |
| `nia doctor` | Run diagnostics for common issues (auth, API, disk access) |
| `nia whoami` | Show current authenticated user |
| `nia version` | Show CLI version |
| `nia version --check` | Check for available updates |

### Sync Control

| Command | Description |
| - | - |
| `nia pause <ID>` | Pause continuous sync for a source |
| `nia resume <ID>` | Resume continuous sync for a source |
| `nia resync <ID>` | Force full resync by resetting cursor |
| `nia resync --all` | Force full resync for all sources |

### Web Integration

Open Nia web app pages directly from the CLI:

```bash theme={null}
nia open dashboard      # Open main dashboard
nia open activity       # Open activity feed
nia open local-sync     # Open local sync settings
nia open api-keys       # Open API keys page
nia open billing        # Open billing page
nia open docs           # Open documentation
nia open <source-id>    # Open specific source detail page
```

***

## Configuration Management

### Config Commands

Manage CLI settings directly from the terminal:

```bash theme={null}
# View all config
nia config list

# Get a specific value
nia config get api_url

# Set a value
nia config set api_url "https://api.trynia.ai"
```

### Ignore Patterns

Customize which files are excluded from sync:

```bash theme={null}
# List current ignore patterns
nia ignore list

# Ignore a directory name
nia ignore add --dir node_modules

# Ignore a file name
nia ignore add --file .DS_Store

# Ignore a file extension
nia ignore add --ext .log

# Ignore a path substring
nia ignore add --path /build/

# Remove an ignore pattern
nia ignore remove --ext .log
```

### Watch Directories

Configure which directories are scanned for auto-linking sources:

```bash theme={null}
# List watched directories
nia watch list

# Add a directory to watch
nia watch add ~/Projects

# Remove a watch directory
nia watch remove ~/Projects
```

> [!TIP]
>
> When you create a folder in a watched directory that matches an unlinked source's name, Nia automatically discovers and links it.

***

## Source ID Shortcuts

You don't need to type full UUIDs. Nia accepts:

* **ID prefixes**: `nia info a3f2` matches `a3f2b1c8-...`
* **Display names**: `nia pause "My Notes"` matches by folder name

If a prefix is ambiguous (matches multiple sources), you'll be prompted with the matches.

***

## Daemon Mode

Running `nia` without arguments starts the sync daemon with real-time file watching:

```
NIA Nia Sync Engine

● real-time file watching
● 3 source(s) active
● Auto-refresh every 30s

Ctrl+C to stop
```

The daemon:

* Watches for file changes using native filesystem events
* Syncs changes within seconds of detection
* Periodically refreshes the source list from the web UI
* Auto-discovers new folders matching unlinked sources
* Sends heartbeats to mark daemon as online

### Daemon Flags

| Flag | Default | Description |
| - | - | - |
| `--watch/--poll` | `--watch` | Real-time watching vs interval polling |
| `-f, --fallback` | 600 | Fallback sync interval in seconds (catches missed events) |
| `-r, --refresh` | 30 | How often to check for new sources from web UI |

***

## Supported Data Sources

Nia Sync automatically extracts and indexes content from various data sources:

> [card] Chat & Messages
>
> * **iMessage** (`~/Library/Messages/chat.db`)
> * **WhatsApp** (`ChatStorage.sqlite`)
> * **Telegram** (JSON exports, ZIP files)

> [card] Apple Ecosystem
>
> * **Apple Notes** (`NoteStore.sqlite`)
> * **Apple Contacts** (AddressBook / vCard)
> * **Apple Reminders** (SQLite)
> * **macOS Stickies** (Stickies DB / plist)

> [card] Browser History
>
> * **Safari** (`~/Library/Safari/History.db`)
> * **Chrome** / **Brave** / **Edge**
> * **Firefox**

> [card] Media & Files
>
> * **Screenshots** (metadata + optional OCR text)
> * Generic **SQLite** databases
> * Regular folders with text files, code, notes

### Virtual File Format

Database content is extracted into virtual text files for semantic search:

| Source | Virtual Path Format |
| - | - |
| iMessage | `messages/{contact}/{date}_{row_id}_{direction}.txt` |
| WhatsApp | `whatsapp/{contact}/{date}_{msg_id}.txt` |
| Safari/Chrome/Firefox | `history/{domain}/{date}_{id}.txt` |
| Telegram | `telegram/{chat_name}/{date}_{msg_id}.txt` |
| Apple Notes | `notes/{folder}/{note_title}_{id}.txt` |
| Screenshots | `screenshots/{date}_{filename}.txt` |

***

## Web UI

You can also manage synced sources from the Nia web app:

1. Go to [app.trynia.ai](https://app.trynia.ai)
2. Navigate to **Settings → Local Sync**
3. View sync status, add/remove sources, and configure sync intervals

### Sync Intervals

Configure how often sources are synced:

| Interval | Description |
| - | - |
| `5m` | Every 5 minutes |
| `hourly` | Every hour |
| `6h` | Every 6 hours |
| `daily` | Once per day |

***

## Searching Local Folders

Once synced, your local folders are searchable via MCP tools:

```python theme={null}
# Search across local folders
search(query="meeting notes from last week", local_folders=["folder-id-here"])

# Read files from a local folder
nia_read(source_type="local_folder", local_folder_id="folder-id-here", path="/notes/meeting.txt")

# Grep in local folders
nia_grep(source_type="local_folder", local_folder_id="folder-id-here", pattern="TODO")

# Explore folder structure
nia_explore(source_type="local_folder", local_folder_id="folder-id-here", action="tree")
```

> [!NOTE]
>
> Local folders are private and searched separately from public repositories. Use `local_folders` parameter in `search()` to include them.

***

## Configuration

### Environment Variables

| Variable | Default | Description |
| - | - | - |
| `NIA_API_URL` | `https://api.trynia.ai` | Override API base URL |

### Config File

Credentials are stored in `~/.nia-sync/config.json` with secure permissions (mode 0600).

***

## Limits

| Limit | Value |
| - | - |
| Max files per folder | 5,000 |
| Max total upload size | 100 MB per folder |
| Max individual file size | 5 MB |
| Max database size | 1 GB |
| Max rows per table | 100,000 |

***

## Security

> [!NOTE]
>
> **350+ exclusion patterns** automatically protect sensitive files from being synced.

The following are **never synced**:

* **Credentials**: `.env`, `.pem`, `.key`, SSH keys, `*credentials*`, `*secrets*`, `*token*`
* **Version control**: `.git`, `.svn`
* **Dependencies**: `node_modules`, `venv`, `__pycache__`
* **Build outputs**: `dist/`, `build/`, `.next/`

API keys are stored locally with user-only read/write permissions and are never logged or transmitted in plaintext.

### End-to-End Encryption

For sensitive personal data (messages, contacts, notes), Nia supports **E2E encrypted sync** where plaintext never leaves your device. The server stores only ciphertext and encrypted vectors.

> [card] [E2E Encryption Guide](https://docs.trynia.ai/e2e-encryption.md)
>
> Learn how E2E encryption works, supported source types, key management, and cookbook examples for syncing iMessage, WhatsApp, Apple Notes, and more.

***

> [!WARNING]
>
> **Need Help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) or reach out through [app.trynia.ai](https://app.trynia.ai/) for support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.