Documentation
Documentation
ConfigSync v2 -- cross-machine sync for projects, configs, modules, and profiles.
npm install -g @inventivehq/configsync
Concepts
The full conceptual model is in the Architecture document. This section covers the essentials.
Entity types
ConfigSync v2 has exactly five user-owned entity types. Every entity is versioned and encrypted.
| Entity | What it represents |
|---|---|
| project | A git repository plus associated dotfiles and env-file declarations. |
| workspace | A logical grouping of projects (e.g. "Acme Corp" with ten repos). |
| config | A single top-level dotfile or directory tracked independently (~/.zshrc, ~/.gitconfig). |
| module | A bundle of files and settings for a specific tool (ssh, vscode, claude-code, git, zsh, etc.). |
| profile | A container of workspaces, modules, and packages that activates together. Maps to a real-world context like a client, "work vs personal," etc. |
Envelope encryption
Your master password derives a KEK (via PBKDF2, 600k iterations) which unwraps an X25519 keypair stored on the server. That keypair unwraps per-entity DEKs, which decrypt the actual content blobs (AES-256-GCM).
Quickstart
Five minutes from install to your first synced entity.
1. Install
npm install -g @inventivehq/configsync
2. Log in (first machine)
On your first machine, login creates your X25519 keypair and a default profile.
configsync login --token <your-token>
3. Track a project
configsync project add ~/git/my-app
4. Set environment variables
configsync vars set API_KEY=sk-xxx --project my-app --env dev
5. Push
configsync push
6. On another machine
configsync login --token <your-token> # unwraps your keypair
configsync pull --project my-app # clones + restores envs
configsync sync # bidirectional from here on
Commands
Full reference for every command group. Flags are sourced from the CLI source code.
configsync project
Manage projects (v2 entity).
project add <dir>Register a project and push an initial version.project listList projects.project show <slug>Show a project.project rename <oldSlug> <newName>Rename a project.project delete <slug>Soft-delete a project.| --name <slug> | Project slug (defaults to directory name). |
| --git-url <url> | Override detected git remote URL. |
| --git-branch <branch> | Override detected git branch. |
| --force | Skip confirmation on delete. |
configsync project add ~/git/alert24 --name alert24
configsync workspace
Group projects into workspaces; manage membership.
workspace add <name>Create a new workspace and push an empty initial version.workspace listList workspaces.workspace show <slug>Show a workspace and its member projects.workspace rename <oldSlug> <newName>Rename a workspace.workspace delete <slug>Soft-delete a workspace.workspace add-project <wsSlug> <projSlug>Add a project to a workspace.workspace remove-project <wsSlug> <projSlug>Remove a project from a workspace.| --description <text> | Optional description (add). |
| --force | Skip confirmation on delete. |
configsync workspace add acme --description "Acme Corp projects"
configsync config
Track top-level dotfiles as first-class entities.
config add <filePath>Register a config file as a new entity and push v1.config listList config entities.config show <slug>Show a config entity.config rename <oldSlug> <newName>Rename a config entity.config delete <slug>Soft-delete a config entity.| --name <slug> | Entity slug (defaults to filename). |
| --source-hint <text> | Where the config originated (e.g. ~/.zshrc). |
| --force | Skip confirmation on delete. |
configsync config add ~/.zshrc --source-hint "~/.zshrc"
configsync module
Capture and apply tool-specific bundles from the module catalog.
module add <moduleType>Register a module entity and capture its default files.module listList module entities.module show <slug>Show a module entity.module delete <slug>Soft-delete a module entity.| --force | Skip confirmation on delete. |
configsync module add ssh
configsync profile
Containers of workspaces, modules, and packages. Activate and switch.
profile add <slug>Create a new cloud profile entity.profile listList all profiles and mark the active one.profile show [name]Show details of a profile (defaults to active).profile rename <oldSlug> <newName>Rename a cloud profile.profile delete <name>Delete a profile.profile add-workspace <profile> <workspace>Attach a workspace to a profile.profile remove-workspace <profile> <workspace>Detach a workspace from a profile.profile add-package <profile> <package>Add a package to a profile.profile remove-package <profile> <package>Remove a package from a profile.profile activate <slug>Activate a cloud profile on this machine.profile deactivate <slug>Deactivate a cloud profile on this machine.| --name <name> | Display name (default: slug). |
| --description <text> | Description. |
| --default | Mark as the default profile. |
configsync profile add acme --description "Acme Corp work"
configsync vars
Structured environment variables per project and tier.
vars set KEY=VALUE --project <slug> --env <tier>Set a variable.vars unset KEY --project <slug> --env <tier>Delete a variable.vars list --project <slug> --env <tier>List variables in a project/env.vars render --project <slug> --env <tier>Output a composed .env file (stdout).vars push --from-file .env --project <slug> --env <tier>Bulk-import a .env file.| --project <slug> | Project slug (required). |
| --env <tier> | Environment tier: dev, staging, prod, ... (required). |
| --visibility <v> | shared | personal (default: shared). |
| --show | Decrypt and print values instead of masking (list). |
| --description <text> | Human description for the variable (set). |
| --required | Mark the variable as required (set). |
| --from-file <file> | .env file to import (push). |
configsync vars set DATABASE_URL=postgres://... --project alert24 --env dev
configsync sync
Per-entity 3-way sync with conflict modes.
syncBidirectional sync: pull + push linked entities with 3-way conflict resolution.| --cloud-wins | On conflict, prefer cloud version over local. |
| --local-wins | On conflict, prefer local version. |
| --prompt | Prompt per-entity on conflict. |
| --dry-run | Report sync actions without applying them. |
| --entity <type/slug> | Scope sync to a single entity (e.g. project/alert24). |
| -y, --yes | Skip confirmation prompt. |
| --no-delete-local | Keep local environments even if deleted on cloud. |
| --no-delete-cloud | Keep cloud environments even if deleted locally. |
| --legacy-only | Only run legacy environment reconciler. |
| --skip-content | Skip v2 entity content sync. |
configsync sync --dry-run
configsync pull
Materialize entities onto the local machine.
pull --project <slug>Pull a specific project (v2 entity-based flow).pullPull and restore state from sync backend (legacy).| --project <name> | Pull a specific project by slug. |
| --path <dir> | Target directory for --project pull. |
| --force | Overwrite existing files without backup. |
| --dry-run | Preview what would be restored without making changes. |
| --install | Install missing packages after pull. |
| --install-yes | Install missing packages without prompting. |
| --no-packages | Skip package reconciliation. |
| --no-delete | Pull cloud additions without removing local-only environments. |
| --cloud-wins | On conflict, prefer cloud version over local. |
| --snapshot <id> | Restore a specific snapshot by ID. |
| --filter <filters...> | Only pull specific items (e.g. modules:ssh,configs). |
| --skip-bootstrap | Skip bootstrap script execution. |
| --rerun-bootstrap | Force re-run bootstrap even if already done. |
| -y, --yes | Skip confirmation prompt. |
configsync pull --project my-app --path ~/git/my-app
configsync push
Explicit one-direction push.
pushPush current state to sync backend.| -m, --message <msg> | Message describing this snapshot. |
| -y, --yes | Skip confirmation prompt. |
| --no-delete | Push local additions without removing cloud-only environments. |
| --no-cache | Skip hash cache and re-encrypt all files. |
| --filter <filters...> | Only push specific items (e.g. modules:ssh,configs). |
| --changed | Only push items changed since last push. |
configsync push -m "updated vscode settings"
configsync history
Per-entity version history and whole-state snapshots.
historyList past sync snapshots.history --project <slug>Show version history for a project entity.history --workspace <slug>Show version history for a workspace entity.history --config <slug>Show version history for a config entity.history --module <slug>Show version history for a module entity.history --profile <slug>Show version history for a profile entity.| -n, --limit <n> | Number of entries to show (default: 20). |
| --from <machine> | Filter by machine name or ID (snapshot mode). |
configsync history --project alert24 -n 10
configsync diff
Compare local state against a specific entity version or remote state.
diff --project <slug> --version <n>Diff a project entity against a historical version.diffShow differences between local files and remote state (legacy).| --project <slug> | Diff a project entity version. |
| --workspace <slug> | Diff a workspace entity version. |
| --config <slug> | Diff a config entity version. |
| --module <slug> | Diff a module entity version. |
| --profile <slug> | Diff a profile entity version. |
| --version <n> | Entity version to diff against (required with entity flags). |
| --stat | Show summary only (no content diff). |
| --name-only | Show only file paths that differ. |
| --from <machine> | Diff against a specific machine (legacy). |
| --snapshot <id> | Diff against a specific snapshot (legacy). |
| --filter <filters...> | Only diff specific items (legacy). |
configsync diff --project alert24 --version 3 --stat
configsync rollback
Roll a single entity or a whole-state snapshot back to a previous version.
rollback --project <slug> --version <n>Roll back a project to a previous version.rollback --workspace <slug> --version <n>Roll back a workspace.rollback --config <slug> --version <n>Roll back a config.rollback --module <slug> --version <n>Roll back a module.rollback --profile <slug> --version <n>Roll back a profile.rollback --snapshot <n>Legacy whole-state snapshot restore.| --version <n> | Target version number (required for entity rollback). |
| --snapshot <n> | Legacy whole-state snapshot ID. |
configsync rollback --project alert24 --version 3
configsync env
Environment tiers (dev/staging/prod). Not to be confused with vars (variables).
env listList environments and mark the active one.env create <name>Create a new environment.env activate <name>Persistently activate an environment.env deactivateClear the active environment.env currentShow the currently active environment.env shell <name>Spawn a subshell with an environment activated (resets on exit).env hook <shell>Print shell hook code for prompt integration (bash, zsh, fish).env delete <name>Delete an environment definition.env varsOutput export statements for the current project/environment.| --tier <tier> | Environment tier: development, staging, production, custom (create). |
| --color <hex> | Color override (create). |
| --protect | Require type-name confirmation for destructive ops (create). |
| --api-url <url> | Per-env API URL (create). |
| --for-shell | Output in shell-eval-friendly format (vars). |
configsync env create staging --tier staging --protect
configsync login / init / status / list / doctor / scan / watch
Authentication, diagnostics, and background sync.
loginLog in to ConfigSync cloud on this machine. Fetches and unwraps your keypair, or creates one on first login.initInitialize ConfigSync on this machine. Generates X25519 keypair, creates default profile.statusShow current sync status.listShow all tracked items organized by type.doctorCheck the health of your ConfigSync installation.scanScan for installed packages and save to sync state.watchWatch tracked files and auto-push on changes.| --token <token> | API token (login, init). |
| --api-url <url> | API base URL (login, init). Default: https://configsync.dev. |
| --sync-backend <backend> | Sync backend: local | cloud (init). Default: cloud. |
| --profile <name> | Profile name (init). Default: default. |
| --debounce <ms> | Debounce delay in milliseconds (watch). Default: 5000. |
| --diff | Show diff against remote packages without installing (scan). |
configsync login --token cs_abc123
Reference
Architecture
Entities, envelope encryption, sync semantics, profiles, storage layout.
D1 Schema
Tables, columns, indexes. Single source of truth: schema.sql.
AAD Design (Refactor Plan)
Full v2 implementation plan including the crypto reconciliation addendum.
Environment variables
These are environment variables that configure the CLI itself, not the per-project variables managed by configsync vars.
| Variable | Purpose |
|---|---|
| CONFIGSYNC_MASTER_PASSWORD | Master password for non-interactive use (CI, scripts). Avoids the TTY prompt. |
| CONFIGSYNC_MASTER_PASSWORD_FILE | Path to a file containing the master password (one line). |
| CONFIGSYNC_PROFILE | Override the active profile for the current session. |
| CONFIGSYNC_ENV | Override the active environment tier for the current session. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Clean. |
| 1 | General error. |
| 2 | Sync conflict with no resolution strategy. |
| 3 | Authentication failure. |