Keep local .md and .mdx files in sync with cloud Papers on your Infa board.
File sync lets you keep local Markdown and MDX files in sync with Papers on your Infa board. Each local file is linked to a cloud Paper via a paper_id in its frontmatter.
File has no paper_id — not yet linked to a cloud Paper
[x]
error
Could not compare (fetch failed, etc.)
Copy link
Push a file to cloud
infa sync push docs/setup.mdx
Uploads the local file content to the linked cloud Paper. Creates a new Paper if none exists and writes the paper_id back into the file's frontmatter.
Copy link
Pull a file from cloud
infa sync pull docs/api.mdx
Overwrites the local file with the cloud Paper's current content.
Pull overwrites local changes
There is no merge — pulling replaces the local file entirely. Check sync status first if you have uncommitted local edits.
Copy link
How files are linked
A local file is linked to a cloud Paper when it contains a paper_id in its frontmatter:
docs/setup.mdx
Copy code
Copy code
---
title: "Setup Guide"
paper_id: paper_abc123
last_edited_at: "2026-03-21T10:00:00.000Z"
---
Content here...
When you push a file that has no paper_id, a new Paper is created on the board and the frontmatter is updated automatically. When you pull, last_edited_at is updated.
Copy link
Background polling
While infa preview is running, the sync service polls for status changes every 30 seconds and broadcasts updates to the web UI via WebSocket. You do not need to run infa sync manually in this mode — the web UI shows sync state in real time.
Copy link
Sync via the HTTP API
The running preview server also exposes sync over HTTP:
# Check status
curl http://localhost:7100/api/sync/status
# Push a file
curl -X POST http://localhost:7100/api/sync/push \
-H "Content-Type: application/json" \
-d '{"path": "docs/setup.mdx"}'
# Pull a file
curl -X POST http://localhost:7100/api/sync/pull \
-H "Content-Type: application/json" \
-d '{"path": "docs/api.mdx"}'
These endpoints return 404 if no board is configured.
File Sync
File sync lets you keep local Markdown and MDX files in sync with Papers on your Infa board. Each local file is linked to a cloud Paper via a
paper_idin its frontmatter.Requirements: authenticated (
infa auth) + board connected (infa board).Lists every discovered local file and its current sync state:
[v]in_sync[^]local_ahead[↓]cloud_ahead[!]conflict[-]unlinkedpaper_id— not yet linked to a cloud Paper[x]errorUploads the local file content to the linked cloud Paper. Creates a new Paper if none exists and writes the
paper_idback into the file's frontmatter.Overwrites the local file with the cloud Paper's current content.
A local file is linked to a cloud Paper when it contains a
paper_idin its frontmatter:When you push a file that has no
paper_id, a new Paper is created on the board and the frontmatter is updated automatically. When you pull,last_edited_atis updated.While
infa previewis running, the sync service polls for status changes every 30 seconds and broadcasts updates to the web UI via WebSocket. You do not need to runinfa syncmanually in this mode — the web UI shows sync state in real time.The running preview server also exposes sync over HTTP:
These endpoints return
404if no board is configured.