Getting Started

This guide is the fastest way to go from a fresh machine to your first local Markdown sync with the full-screen TUI.

1. Install syncdown

If syncdown is not already available on your PATH, install the prebuilt binary first.

syncdown publishes release binaries for:

darwin-arm64
darwin-x64
linux-x64
windows-x64

On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/hjinco/syncdown/main/scripts/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/hjinco/syncdown/main/scripts/install.ps1 | iex

Manual downloads are also available from the GitHub Releases page.

2. Launch the TUI

Open an interactive terminal and run:

syncdown

This opens the OpenTUI app. It includes:

• setup screens for your output path and connector auth
• diagnostics and system paths
• a sync dashboard for running connectors and watching logs

If you run syncdown without a TTY, it prints help instead of opening the UI.

3. Choose an output directory

In the TUI, open Output and select a preset or enter a custom path.

syncdown normalizes the path before saving it and writes rendered Markdown underneath that directory.

Treat the Markdown files and connector folders under that output tree as syncdown-managed output. It is best not to manually edit, rename, move, or reorganize generated .md files or folders there, because later syncs or full resyncs may recreate, overwrite, or remove them.

4. Connect a source

Notion

Open Connectors → Notion and choose one of these flows:

• Connect with Token: syncdown opens the Notion integrations page, then asks for the integration token.
• Connect with OAuth: syncdown asks for your Notion public integration client ID and client secret, opens the browser, and waits for the local callback.

Gmail

Open Connectors → Gmail and choose Connect Google account.

The TUI asks for your Google Desktop app client ID and client secret, opens the browser, and completes the OAuth callback locally.

Google Calendar

Open Connectors → Google Calendar.

Use Connect Google account if you do not already have a shared Google account connected, then open Select calendars and choose the calendars you want to sync.

5. Run your first sync

From the TUI home screen, open Sync and choose:

• Run all
• Run Notion
• Run Gmail
• Run Google Calendar

Recent connector logs and run status stay visible in the same dashboard.

If you want a headless CLI loop instead, run:

syncdown run --watch
syncdown run --watch --interval 5m

If you omit --interval, the default is 1h.

6. Confirm the result

Check your output directory for Markdown files grouped by connector.

You can also inspect the current app state from the CLI:

syncdown status
syncdown connectors
syncdown doctor

Next steps

• Use Configuration if you want to set up syncdown without the TUI.
• Use CLI if you want the full command reference.
• Use Connectors if you want connector-specific setup details.