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

# Synchronization

> Sync and update your agent's context

## nao sync

The `nao sync` command populates your context folder with content from configured sources.

```bash theme={null}
nao sync
```

You can limit a sync to specific providers with `--provider` (or `-p`).

```bash theme={null}
nao sync --provider databases
```

Supported provider values are:

* `databases` (aliases: `db`, `dbs`, `database`)
* `repositories` (aliases: `repo`, `repos`, `repository`)
* `notion`

You can also target one configured connection by using `provider:connection-name`:

```bash theme={null}
nao sync --provider databases:my-db
nao sync -p repositories:dbt_project
nao sync -p databases -p notion
```

Use this when you want to refresh only part of your context instead of running every configured sync provider.

**Sync specific schemas or tables with `--select`**

By default, if you narrow a database sync to a subset of tables, `nao sync` removes any previously-synced table or schema that was not part of the run. Use `--select` (or `-s`) to refresh only a selection **without deleting the rest** of your synced context.

```bash theme={null}
# Sync a single table
nao sync --select analytics.orders

# Sync a whole schema
nao sync --select analytics

# Multiple selections and glob patterns
nao sync -s analytics.orders -s staging.dim_*

# Combine with a specific connection
nao sync -p databases:my-warehouse -s analytics.orders
```

Behavior:

* A pattern with **no dot** (`analytics`) selects every table in that schema (`analytics.*`).
* A pattern with a **dot** (`analytics.orders`) selects a specific table; glob wildcards are supported (`staging.dim_*`).
* Selection is applied **on top of** the existing `include` / `exclude` config in `nao_config.yaml`: it narrows further, never widens.
* When `--select` is passed, stale-path cleanup is skipped, so tables and schemas outside the selection are preserved.
* Tables and Snowflake semantic views both respect the selection.

Use this to refresh one table on a large warehouse without re-syncing everything.

**Run the sync in parallel**

By default `nao sync` uses a single worker thread. Speed up large syncs with `-t` / `--threads`:

```bash theme={null}
nao sync --threads 4
```

This overrides the `threads` value in `nao_config.yaml` (which itself defaults to `1`). The value must be `1` or greater.

**What Gets Synced**

When you run `nao sync`, the following happens:

**1. Database Schemas**

For each database in your `nao_config.yaml`:

* **Connect** to the database
* **Extract schema information** (tables, columns, data types)
* **Generate context files** in `databases/` folder
* **Create structured files** for each table:
  * `columns.md` - Column definitions and types
  * `description.md` - Table description (if available)
  * `preview.md` - Sample data preview
  * `profiling.md` - Data profiling information

Example structure after sync:

```
databases/
└── type=snowflake/database=analytics/
    ├── table=customers/
    │   ├── columns.md
    │   ├── description.md
    │   ├── preview.md
    │   └── profiling.md
    └── table=orders/
        ├── columns.md
        ├── description.md
        ├── preview.md
        └── profiling.md
```

**2. Repositories**

For each repository in your configuration:

* **Clone or pull** the latest code
* **Extract relevant files** from specified paths
* **Index content** for the agent
* **Store** in `docs/` folder

**3. Indexing**

After syncing:

* **Content is indexed** for fast semantic search
* **Embeddings are created** for relevant context retrieval
* **Agent can access** all synced information

## Scheduling

### GitHub Actions

Set up automated syncing with GitHub Actions to keep your context up to date.

**1. Create Workflow File**

This workflow will regularly run `nao sync` on GitHub's servers, commit any changes to your context files (like updated database schemas or docs), and push them back to your repository so your context stays in sync without manual commands.

Create `.github/workflows/nao-sync.yml` in your repository:

```yaml theme={null}
name: Nao Sync

on:
  schedule:
    - cron: "0 0 */2 * *"  # every 2 days at 00:00 UTC
  workflow_dispatch:  # allows manual triggering

jobs:
  nao-sync:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # needed to commit changes

    env:
      NAO_CONFIG_PATH: ./nao_config.yaml

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.ref }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Nao CLI
        run: |
          pip install --upgrade pip
          pip install nao-core
          pip install "ibis-framework[bigquery]"  # warehouse driver for your DB

      - name: Run nao sync
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_APPLICATION_CREDENTIALS_JSON: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY_JSON }}
          # Add other secrets as needed (e.g., NOTION_API_KEY, etc.)
        run: nao sync

      - name: Configure Git
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"

      - name: Commit and push changes
        run: |
          git add -A
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "nao sync update"
            git push origin HEAD:${{ github.ref_name }}
          fi
```

**2. Configure Repository Secrets**

In your GitHub repository:

1. Go to **Settings** → **Secrets and variables** → **Actions**
2. Click **"New repository secret"**
3. Add secrets for all environment variables used in your `nao_config.yaml`:
   * `ANTHROPIC_API_KEY` - Required for `nao sync` to run the agent
   * `GCP_SERVICE_ACCOUNT_KEY_JSON` - Full JSON content of your BigQuery service account
   * `NOTION_API_KEY` - If using Notion integration
   * Any other credentials referenced in your config

<Warning>
  Never commit secrets directly in your workflow file. Always use GitHub Secrets.
</Warning>

**3. Customize Schedule**

Adjust the cron schedule to match your needs:

```yaml theme={null}
on:
  schedule:
    - cron: "0 0 * * *"      # Daily at midnight UTC
    - cron: "0 0 */2 * *"    # Every 2 days
    - cron: "0 0 * * 1"      # Weekly on Monday
    - cron: "0 3 * * *"      # Daily at 3 AM UTC
```

**4. Manual Trigger**

You can manually trigger the sync:

* Go to **Actions** tab in your repository
* Select **"Nao Sync"** workflow
* Click **"Run workflow"**

**5. Monitor Sync Results**

* Check the **Actions** tab to see sync history
* Review logs if sync fails
* Verify changes are committed to your repository

<Info>
  The workflow automatically commits and pushes any changes from `nao sync` back to your repository, keeping your context files up to date.
</Info>

**Next Steps**

<CardGroup cols={2}>
  <Card title="Context Providers" icon="plug" href="/nao-agent/context-builder/databases">
    Learn about configuring databases and repos
  </Card>

  <Card title="Context Engineering Playbook" icon="book" href="/nao-agent/context-engineering/playbook">
    Learn how to measure, iterate, and optimize your context
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Start Chatting" icon="comments" href="/nao-agent/chat/overview">
    Use your synced context with the agent
  </Card>

  <Card title="Context Principles" icon="lightbulb" href="/nao-agent/context-engineering/principles">
    Understand core principles for effective context engineering
  </Card>
</CardGroup>