Skip to main content
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:
motion-source.json
For a GitHub file, give the repository URL, the branch, and the file’s path in the repository:
motion-source.json
Then save a new instruction from it, or connect an instruction you already have:
Rivet reads the file right away. Images the Markdown links to come along too.
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.
Agents use the MCP tool rivet_refresh_sources instead. See the reference. 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

Design context

See the other ways to show Rivet what you mean.