> ## 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.

<Frame>
  <iframe src="https://www.youtube.com/embed/vDOA1ealkp8" title="Local Sync Demo" className="w-full aspect-video rounded-xl" allowFullScreen />
</Frame>

<Info>
  **Privacy First**: Local folders are private to your account. They're searched separately from public repositories and documentation.
</Info>

***

## 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](/integrations/installation/overview) to set up the current CLI.
</Warning>

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

***

## Getting Started

<Steps>
  <Step title="Login">
    Authenticate with your Nia account:

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

    This opens your browser for secure OAuth authentication.
  </Step>

  <Step title="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.).
  </Step>

  <Step title="Start Syncing">
    Start the sync daemon:

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

    The daemon watches for file changes and syncs incrementally in real-time.
  </Step>

  <Step title="Check Status">
    View all synced sources:

    ```bash theme={null}
    nia status
    ```
  </Step>
</Steps>

***

## 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.
</Tip>

***

## 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:

<CardGroup cols={2}>
  <Card title="Chat & Messages" icon="message">
    * **iMessage** (`~/Library/Messages/chat.db`)
    * **WhatsApp** (`ChatStorage.sqlite`)
    * **Telegram** (JSON exports, ZIP files)
  </Card>

  <Card title="Apple Ecosystem" icon="apple">
    * **Apple Notes** (`NoteStore.sqlite`)
    * **Apple Contacts** (AddressBook / vCard)
    * **Apple Reminders** (SQLite)
    * **macOS Stickies** (Stickies DB / plist)
  </Card>

  <Card title="Browser History" icon="globe">
    * **Safari** (`~/Library/Safari/History.db`)
    * **Chrome** / **Brave** / **Edge**
    * **Firefox**
  </Card>

  <Card title="Media & Files" icon="image">
    * **Screenshots** (metadata + optional OCR text)
    * Generic **SQLite** databases
    * Regular folders with text files, code, notes
  </Card>
</CardGroup>

### 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.
</Note>

***

## 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

<Info>
  **350+ exclusion patterns** automatically protect sensitive files from being synced.
</Info>

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 title="E2E Encryption Guide" icon="lock" href="/e2e-encryption">
  Learn how E2E encryption works, supported source types, key management, and cookbook examples for syncing iMessage, WhatsApp, Apple Notes, and more.
</Card>

***

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