Description
Connections and Sync Management is the terminal control plane for bringing external sources into Dots and keeping them reconciled over time. dots connections handles provider authorization, callback completion, catalog reads, and revocation. dots sync binds a source to a target, reports status, pauses or runs it, performs one-shot sweeps, and watches local bindings for changes.
The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Separates reusable account authorization from individual source-to-Dotabase bindings.
- Supports one-shot reconciliation and long-running watch workflows from the same surface.
- Makes binding status and failures visible to headless operators and agents.
- Allows a problematic source to be paused without deleting its configuration.
- Works with pluggable connector definitions while retaining a consistent operational command set.
User Story
An operator authorizes a source account, creates a binding into a chosen Dotabase, runs an initial sweep, and then starts a narrowed watcher for that binding. When the source needs maintenance, they pause it and can later resume without rebuilding the mapping. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The CLI surface is automatable: packages/cli/src/commands/connections.ts and packages/cli/src/commands/sync.ts bind the operational verbs. Connector implementations are pluggable through the SDK, but the command family itself is fixed. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: Connection add, authorize, callback-complete, list, and revoke lifecycle.
- Capability: Binding creation, listing, status, pause, run, and one-shot sweep.
- Capability: Scoped local watch loops with target mapping and reconciliation summaries.
- Limit: Available providers and mapping behavior depend on installed connector definitions and their source capabilities; the CLI cannot synthesize unsupported connectors.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/cli/src/commands/connections.tspackages/cli/src/commands/sync.tsdocs/cli/connections-and-sync-commands.md