SyncMatters CLI

sm is the command-line companion to the SyncMatters platform: pull your organization's connectors and integration scripts into a local folder, edit them in your own editor (VS Code, Cursor, anything) with full IntelliSense, and push changes back safely.

Requirements

• Node.js 20 or later
• A SyncMatters account (you will mint a developer token in the web app)

Installation

npm install -g @syncmatters/cli
sm --help

Quick start

1. Mint a developer token: in the SyncMatters web app, open your user settings, select Developer tokens, and create a token. Copy it — it is shown once.

2. Sign in — the token is stored in your OS keychain, never in a file:

   sm auth

3. Pull your workspace into a new folder:

   mkdir my-workspace && cd my-workspace
   sm pull

   This mirrors your organization's script tree into files/ (code) and meta/ (configuration sidecars), and sets up editor tooling so the SDK types light up.

4. Edit, then push:

   sm status                     # what changed locally
   sm diff                       # see the changes
   sm push -m "describe change"  # write them back

   Or leave sm watch running and every save is pushed automatically.

Commands

| Command | What it does | |---|---| | sm auth | Sign in with a developer token. Inside a previously pulled folder it reconnects to that folder's organization. | | sm whoami | Show who you are signed in as, and where. | | sm pull | Download the organization's script tree (safe: never overwrites local edits silently). | | sm status / sm diff | Compare your working copy against what you pulled — locally, no server calls. | | sm push -m "msg" | Upload changed files with optimistic concurrency — if someone changed a file since your pull, the push is rejected instead of overwriting their work. | | sm watch | Auto-push on save (debounced, conflict-safe). | | sm validate | Check workspace structure locally before pushing. | | sm connector init | Scaffold a new connector with a guided wizard. | | sm connector update | Update a connector's settings definition. | | sm mv / sm rm | Rename/move or delete platform files, safely. | | sm profile list/use | Inspect or switch stored sign-ins (profiles are created automatically by sm auth). | | sm run | Run connector test/meta/query operations on the platform (rolling out — currently reports when the capability is unavailable). |

Run any command with --help for options.

How it keeps you safe

• Your token stays in the OS keychain and is exchanged for a short-lived session per command; nothing secret is ever written to the workspace or config files. Revoking the token in the web app cuts the CLI off immediately.
• No lost work: every push carries the version you pulled; if the platform copy moved on, you get a conflict instead of a silent overwrite (sm pull, merge, push again).
• No cross-organization accidents: a workspace is bound to the organization it was pulled from, and every command checks that your current sign-in matches before touching anything.

Working with AI coding assistants

Pulled workspaces are AI-ready: sm pull generates an AGENTS.md that assistants like Cursor and Claude pick up automatically, pointing them at the complete connector-authoring guide that ships inside the @syncmatters/connector-sdk types package. Your assistant learns the SDK contract, the platform's conventions and the common pitfalls without any manual priming.

CI and automation

Set SM_TOKEN to a developer token instead of running sm auth — useful for pipelines that pull or push scripts non-interactively. Mint a dedicated token for CI so it can be revoked independently.

Documentation and support

• Full guides: SyncMatters help — Developer → Working with the CLI (in the web app)
• https://syncmatters.com · [email protected]

License

MIT © SyncMatters