From install to a cross-repo map.
Install the CLI, scan each repo, share the map with your team and your coding agents. Everything below runs on your machine unless it says otherwise.
Overview
ArchSync reads your source, resolves imports and API calls across services, and produces a .archsync-schema.json describing your system — modules, routes, controllers, services, models, and the relationships between them. You review that file in pull requests, visualize it on the canvas, or serve live source over a localhost-only bridge.
Install
Install globally, or run with npx for zero install:
$ npm install -g archsync
# or, no install:
$ npx archsync scanRequires Node.js 18 or newer.
Quickstart
$ archsync login # sign in via your browser (first time only)
$ archsync init # creates .archsync.json + .archsyncignore
$ archsync scan # build .archsync-schema.json
$ archsync push # push schema to your database
$ archsync diff --merged # cross-system contract check (the key one)archsync init automatically adds .archsync.json to your .gitignore and creates an .archsyncignore file with sensible defaults. For a self-hosted instance, add --instance your-domain.com to the login command.
Commands
Run archsync <command> --help for full options.
archsync login/archsync logout— sign in via your browser (device authorization). Run once per machine. Add--instance your-domain.comfor a self-hosted setup.archsync init— guided setup: links a project, writes.archsync.json, creates.archsyncignore, and auto-adds.archsync.jsonto.gitignore.archsync scan— scan source files and write.archsync-schema.json. Respects.archsyncignore. Add--debugto trace what's being parsed.archsync push— push the local schema to your database. Use-bfor branch,--dry-runto preview.archsync diff— show what changed between local and remote schema for this system.archsync diff --merged— cross-system contract check. Merges every connected system's latest schema and tells you what your current change breaks in other services — down to missing fields, type mismatches, and removed routes. Run this before every push. Add--auditto see all standing mismatches, not just what you changed.archsync watch— watch for file changes and auto-rescan.archsync serve— start the localhost-only code bridge (binds127.0.0.1, read-only) so the canvas shows live source.
Configuration
archsync init creates .archsync.json in your project root and automatically adds it to .gitignore. Each developer runs archsync init on their own machine — it's not meant to be committed.
{
"projectId": "acme-platform",
"framework": "node",
"defaultSystem": "backend",
"supabase": {
"url": "https://xxx.supabase.co",
"anonKey": "your-public-anon-key"
},
"scan": {
"include": ["**/*.{js,ts,jsx,tsx,dart}"],
"exclude": ["**/node_modules/**", "**/dist/**"]
}
}The anonKey is the public client key (RLS is the real security layer), so it's not a secret — but .archsync.json is gitignored by default as a precaution.
Ignore patterns (.archsyncignore)
archsync init creates a .archsyncignore file in your project root with sensible defaults. It uses the same syntax as .gitignore — globs, directory trailing slashes, and # comments. Commit this file so the whole team scans the same set of files.
# .archsyncignore — what to exclude from scanning
# Generated files
src/generated/
**/*.g.dart
**/*.freezed.dart
# Vendored SDKs
lib/vendor/
# Test fixtures
**/__fixtures__/ArchSync always skips node_modules, dist, build, and .dart_tool regardless of what's in .archsyncignore. Additional excludes in .archsync.json under scan.exclude are merged in — use those for machine-specific or CI-specific overrides.
Live code (archsync serve)
On the canvas, clicking any entity opens its code next to it. Without the bridge you see the short snippet captured at scan time. Start the bridge and you get the real file, live from your disk — one bridge can serve every repo of a product:
$ archsync serve ../backend ../mobile-app ../admin-webThe bridge binds to 127.0.0.1, is read-only, and only serves files that appear in a scanned schema. In the canvas, every line that calls something else gets a link; clicking it opens the target’s code with an arrow from that exact line.
Context index (archsync embed)
Builds short, metadata-only cards (no source code) for every entity and flow, and stores them in your Supabase so the canvas search and your coding agents can find things by meaning — “cancel an order” finds DELETE /orders/:id.
$ archsync embed --dry-run # build the cards, send nothing
$ archsync embed # uses VOYAGE_API_KEY if set, else full-text onlyEmbeddings use your own key (Voyage voyage-code-3 by default, OpenAI supported). Re-runs only embed what changed. Without a key, search still works using full-text.
MCP for coding agents
Claude Code, Cursor and Windsurf can ask ArchSync which repos a change touches before writing code. The MCP server runs inside your own Supabase:
$ archsync mcp deploy # once per Supabase project (needs the Supabase CLI)
$ archsync mcp token --name laptop # personal, revocable token + editor configs
$ archsync mcp rules >> CLAUDE.md # tell the agent to ask ArchSync firstTools your agent gets: prepare_task, explain_flow, search, get_context, check_change and list_systems. Turn access on or off per project in Settings → Agent access. Prefer local? archsync mcp serves the same tools over stdio from your repo.
Bring your own database
ArchSync is storage-agnostic. Point the CLI at your own Supabase and your architecture data never touches ArchSync servers. Credentials are read from, in order:
- Environment variables —
ARCHSYNC_SUPABASE_URL/ARCHSYNC_SUPABASE_ANON_KEY - The project's
.archsync.json
Database migrations
Before your first push, apply ArchSync's schema to your own Supabase project. Every migration is idempotent — written with IF NOT EXISTS / CREATE OR REPLACE, so re-running is always safe. Everything is bundled into one ordered script.
Fastest path: copy the script, then in the Supabase dashboard open SQL Editor → New query, paste, and run.
Prefer the command line? Apply the downloaded file with psql:
$ psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 \
-f ALL_MIGRATIONS.sql
# SUPABASE_DB_URL = Settings → Database → Connection string (URI)Applying the script sets up:
- Core schema & multi-tenant RLS — projects, nodes/edges, schema commits and diffs, with row-level security so each tenant sees only its own data.
- Team roles —
owner,admin, andmemberper project (see Team & roles below). - Per-system scoped push keys — hashed at rest, validated server-side, and revocable; a key is bound to one system (e.g.
consumer-app,core-backend). - Push approval workflow — pushes from member keys land as
pending; owner/admin keys auto-approve. The live schema is always the latestapprovedcommit. - Email invites, multiple named systems per team, and ownership transfer.
ALL_MIGRATIONS.sql — idempotency means only the new changes apply, so it's always safe to run the latest. This page always serves the current version.Team & roles
The migrations above enable team collaboration on a project. Roles are scoped per project:
- Owner — full control; the only role that manages billing and can transfer ownership.
- Admin — manage members and keys, and approve or reject pending pushes.
- Member — scoped to one or more systems; can push (landing as
pendingfor review) and sees only the keys for systems they're granted.
A team can have multiple apps, web portals, and backends — each a named system (e.g. consumer-app + driver-app, admin-web, payments-backend + core-backend). The push key is the source of truth for which system a push targets, so a contractor holding the driver-app key can only ever push to driver-app. Owners and admins create keys and review pushes directly on the canvas.
Multi-repo setup
ArchSync's cross-system detection works when every repo pushes to the same project ID. Here's the exact flow for a backend developer and a frontend developer:
Step 1 — Developer A sets up the project (backend):
$ archsync login
$ archsync init # "Team / shared" → name it e.g. "payments-backend"
$ archsync scan && archsync pushStep 2 — Developer B links their repo to the same project (frontend / mobile):
$ archsync login
$ archsync init # "Team / shared" → "Enter existing project ID" → paste Developer A's ID
$ archsync scan && archsync pushBoth systems now appear in the same canvas. Either developer can run the cross-system check from their repo:
$ archsync diff --merged # what does my current change break in the other system?archsync scan && archsync push after making changes. diff --merged always reads the latest pushed schema for every system from the shared database.Onboarding a team
One person — the admin — sets the team up; everyone else just accepts an invite. Nobody copies database keys. Permissions are always enforced by the database (RLS + role checks), never by a client token.
Admin — once:
- Sign in at archsync.dev. On ArchSync Cloud, that’s it. For your own Supabase, run the setup SQL there (the Copy SQL button above) and connect it in Settings → Connected Databases.
- Own Supabase only: in your Supabase dashboard → Authentication → URL Configuration, add
https://archsync.dev/**to Redirect URLs so invite emails can bring people back to ArchSync. - Own Supabase, optional: Supabase’s built-in email sends only a few messages an hour. For real teams, add any SMTP provider in Authentication → Emails → SMTP Settings. To word the invite email your way, edit Authentication → Emails → Templates → Confirm signup (new people) and Magic Link (people who already have an account).
{{ .Data.invited_by }}and{{ .Data.project_name }}are filled in for new accounts; always keep{{ .ConfirmationURL }}as the link. - Invite people from Settings → Team & Systems. They get an email; you also get a link you can share yourself.
Teammate — join:
- Open the invite email (or link). It connects your browser to the team’s database — you see which one and confirm — signs you in and adds you to the project.
- Install the CLI and log in. The browser you joined with approves it, and the CLI is connected to your team’s database automatically:
$ npm install -g archsync
$ archsync login # opens archsync.dev to approve this device
$ archsync init # lists only the projects you can access
$ archsync scan && archsync pushHow the CLI finds your team’s database: archsync login starts on archsync.dev with a one-time secret in the approval link. The browser you approve in is connected to your team’s database, so it signs the CLI in there and passes back that database’s address, sealed with the secret — archsync.dev only ever relays ciphertext. Each login appears under Settings → CLI Devices, where you can revoke it. Running your own copy of the website? Use archsync login --instance your-domain.
CI & pull requests
Add ArchSync to CI to block PRs that break cross-system contracts. diff --merged exits non-zero when breaking changes are detected.
# GitHub Actions example
- name: ArchSync cross-system check
env:
ARCHSYNC_SUPABASE_URL: ${{ secrets.ARCHSYNC_SUPABASE_URL }}
ARCHSYNC_SUPABASE_ANON_KEY: ${{ secrets.ARCHSYNC_SUPABASE_ANON_KEY }}
run: |
npm install -g archsync
archsync scan
archsync diff --merged # fails if this change breaks another systemFor a machine-readable diff (to post as a PR comment or parse in scripts):
$ archsync diff --json # added/removed/modified, single-system
$ archsync diff --merged --json # cross-system contract violationsBilling & credits
ArchSync has three ways to use it:
- Free — one person on their own repos:
scan,diff,validate,explain,serve,watchand the canvas on local files. No account, never metered. - Solo — adds
archsync mcpfor your own AI agent. One person. - Team — adds everything shared:
archsync pushto your own Supabase, the team canvas, hosted MCP for every teammate, members and roles.
Solo and Team are paid with prepaid credits, not a subscription. You buy a pack once; credits never expire, and paid actions draw them down. Nothing renews and there is nothing to cancel.
Credits belong to an organisation, not a seat, and are capped by a rolling 5-hour window (below). Your architecture data still lives entirely in your own database — ArchSync billing only stores your account email, organisation, credit balance and a usage log.
The 5-hour usage window
Credits are capped by a rolling 5-hour window, not drained all at once. Your tier sets how many credits you can spend in any 5-hour span; spend freely under that ceiling, and the window rolls forward continuously. This keeps day-to-day work feeling unlimited while smoothing big bursts.
Tiers (higher = more throughput per 5 hours):
- Free — a small window to get started.
- Pro — a larger window for active teams.
- Max — the largest window for heavy, continuous use.
Raising your tier is a one-time unlock, not a subscription. The live meter in Settings → Billing always shows how much of your current window is used and when it resets.
What costs credits
Each metered action draws a fixed number of credits. The server is the source of truth for these costs.
| Action | Credits | What it is |
|---|---|---|
archsync push | 2 | Sync a system’s schema to your team database |
Cross-repo merge | 3 | Combine schemas from multiple repos into one canvas |
Breaking-change scan | 2 | Cross-stack impact / blast-radius analysis |
AI insight | 4 | AI architecture recommendation (LLM inference) |
Canvas session | 1 | A day of active shared-canvas use, per user |
MCP session | 2 | An agent connecting to ArchSync MCP (each start of archsync mcp, or each hosted session) |
Export | 1 | PDF or image export of a map |
These are the current defaults — costs are set per action and can change. When the balance runs out, paid actions stop with a clear message until an owner or admin tops up; everything in Free keeps working.
Buying credits
- Open the canvas → Settings → Billing and sign in to your ArchSync account (or create one). Teams on their own database sign in here separately — this account only holds billing.
- Create an organisation and choose Solo or Team. You become its owner and get the organisation key once.
- Choose a pack and pay. Payments are processed by Razorpay. Only the owner or an admin can buy.
- On Team, invite people by email. They join when they sign in with that email, and each creates their own key.
In India you pay in rupees (INR) — UPI, Indian cards, net banking and wallets. Outside India you pay in US dollars with PayPal: choose USD next to “Buy credits” (it is preselected outside India) and the checkout opens PayPal. International cards outside PayPal are not accepted yet.
- Solo — 300 credits (Solo organisations)
- Starter — 200 credits
- Growth — 1,000 credits
- Scale — 3,000 credits
Credits land on your org’s balance as soon as the payment is confirmed. The Billing tab shows your current balance, a breakdown of what you’ve spent, and your recent activity. See pricing for current pack prices.
Activate credits for the CLI
archsync push needs a Team key and archsync mcp needs a Solo or Team key. Each person creates a personal key in Settings → Billing → Use it from the CLI and agents and activates it once per machine. Usage is recorded against that person, and removing someone from the organisation revokes their keys.
$ archsync license activate ask_lic_xxxxxxxx # store & verify your key
$ archsync license status # plan + remaining credits
$ archsync license logout # remove the key from this machineThe key is stored in ~/.archsync/license.json at mode 0600 — the same posture as ~/.npmrc or the AWS CLI. In CI, set it as the ARCHSYNC_LICENSE_KEY secret instead. Once activated, each push uses 2 credits (a cross-repo diff --merged uses 3, an agent session 2) and prints your remaining balance. Paid actions are confirmed with ArchSync before they run, so they need a connection to archsync.dev; everything in Free keeps working offline.
For hosted agent access, an owner or admin runs archsync mcp deploy on a machine where the organisation key is active; it is stored as the function’s secret in your own Supabase. The organisation key can be rotated from Settings → Billing.
Privacy & security
- Scanning is fully local — nothing is uploaded by
scan. archsync servebinds strictly to127.0.0.1, is read-only, and only serves files present in the scanned schema.archsync pushis the only command that sends data anywhere, and only to the database you configure.
Found a gap in the docs? Open an issue.