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

# Syncing sources

> Keep saved instructions in step with a local file or a GitHub file, and keep imported references up to date.

A saved instruction is a copy. If you edit the original file, Rivet keeps using the old text. Connect the instruction to a source, and Rivet pulls in your edits for you. Imported reference collections work the same way.

## Connect a source

A source is a Markdown file in one of two places:

* **A local file** on your computer.
* **A file on a GitHub branch.** Rivet reads it with the GitHub CLI, so sign in with `gh auth login` first.

Describe the source in a small JSON file. For a local file, `path` can be absolute or relative to the JSON file:

```json motion-source.json theme={null}
{ "kind": "file", "path": "./docs/motion.md" }
```

For a GitHub file, give the repository URL, the branch, and the file's path in the repository:

```json motion-source.json theme={null}
{
  "kind": "github",
  "repository": "https://github.com/acme/design-system",
  "branch": "main",
  "path": "docs/motion.md"
}
```

Then save a new instruction from it, or connect an instruction you already have:

```bash theme={null}
rivet context add --title "Motion principles" --source ./motion-source.json
rivet context update <id> --source ./motion-source.json
```

Rivet reads the file right away. Images the Markdown links to come along too.

> [!TIP]
>
> You don't have to run these yourself. Ask your agent: "Save docs/motion.md as my motion principles and keep it in sync with the file."

To stop following the source, run `rivet context update <id> --remove-source`. The instruction keeps its current text.

## Sync modes

Each source has a sync mode:

* `daily` *(default)* — Rivet refreshes the source on its own while Rivet is running. It checks local files about every minute, and GitHub files about once a day.
* `manual` — Rivet refreshes the source only when you ask.
* `off` — Rivet never refreshes the source. Even an explicit refresh of that source fails with `source_sync_off`.

Imported reference collections have sync modes too. With `daily`, Rivet refreshes a collection about 24 hours after its last import or refresh.

## Refresh now

Refresh saved instructions with `rivet context refresh`, and imported reference collections with `rivet profile refresh`. Both take one of:

* `<sourceId>` — refresh one source. For a saved instruction, this is its ID from `rivet context list`.
* `--all` — refresh every connected source. Sources set to `off` are reported as `skipped_off` and left alone.
* `--preview` — show each source's sync mode, last sync, and errors, without contacting any source.

```bash theme={null}
rivet context refresh --preview
rivet profile refresh --all
```

Agents use the MCP tool `rivet_refresh_sources` instead. See the [reference](https://docs.rivet.design/mcp-guide.md#mcp-tools).

A refresh only queues the work and returns. If a saved instruction's source can't be read, Rivet keeps the last good text. A reference refresh reads only the collections you approved and never adds new ones. It can add new items from those collections and start analysis on them, which uses your agent's usage.

## Next

> [card] [Design context](https://docs.rivet.design/design-context.md)
>
> See the other ways to show Rivet what you mean.


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