SynapCLI

A CLI tool for syncing files from a GitHub repository into any project, regardless of language or framework. Designed with AI-assisted development in mind — sharing agent definitions, system prompts, instructions, coding standards, scripts, resources, and any other AI assets across a portfolio of projects — but works equally well for any files you want to distribute from a central source of truth. Requires only Node.js 20.12+ on the target machine. Supports multiple sources, lockfile-based change tracking, tab completion, postpull hooks, and CI/CD mode.

Requirements

• Node.js 20.12+ (the only requirement — works in any project regardless of language or framework)
• Git (used to read token from ~/.gitconfig)

Installation

Install globally so the synap command is available in any project:

npm install -g synapcli
synap --version

Or use via npx without installing:

npx synap <command>

Authentication

Public repositories

No setup needed. Requests are unauthenticated automatically.

Private repositories

SynapCLI reads your GitHub token from two places, in order:

1. OS environment variable

# Mac/Linux
export GITHUB_TOKEN=ghp_yourtoken

# Windows PowerShell
$env:GITHUB_TOKEN="ghp_yourtoken"

2. ~/.gitconfig (recommended — persists across sessions)

git config --global synapcli.githubToken ghp_yourtoken

Or add it manually to ~/.gitconfig:

[synapcli]
    githubToken = ghp_yourtoken

Generate a token at github.com/settings/tokens. For fine-grained tokens, grant Contents: Read-only on the target repository.

Quick Start

Getting started

# Create your config and register your first source
synap init

# Validate your setup end-to-end
synap doctor

# Browse available files in the remote repo
synap list
synap list skills                    # narrow to a subfolder

# Pull all files (with preview + confirm)
synap pull
synap pull --interactive             # choose files from a checklist
synap pull --ref v1.2.0 testing.instructions.md  # pull a specific file at a ref

Staying in sync

# See the status of every tracked file
synap status

# Review upstream changes line by line
synap diff

# Pull only files that have changed
synap update

Managing sources and collections

# Add another source repository
synap register
synap register --from team.collection.json       # import from a collection file

# Remove a source
synap deregister

# Install a curated set of individual files
synap install react-kit.collection.json

# Bundle your tracked files into a shareable collection
synap collection create my-kit

Cleanup

# Remove a tracked file from disk and the lockfile
synap delete summarizer

Shell tab completion is set up during synap init. To install it separately, run synap completion --install.

Looking for a real-world multi-source example? See EXAMPLES.md — pulling Claude skills, Copilot instructions, and custom agents from community GitHub repos all at once.

Commands

synap init

Interactively create a synap.config.json. Supports registering multiple repositories in a single session. Validates your GitHub token on setup, pre-populates the tab completion cache, and offers to install shell tab completion.

synap doctor

Health check for your entire setup — Node version, git, token validity, repo access, output directory permissions, and orphaned lock entries (tracked files that no longer exist locally).

synap doctor

synap list [path]

List all files available in the configured remote repository. Optionally narrow the listing to a subdirectory by passing a path argument.

synap list                          # human-readable output
synap list --json                   # machine-readable JSON for scripting
synap list skills                   # list files under the "skills" folder
synap list --source Agents          # list only from the "Agents" source
synap list guides --source Prompts  # list "guides" folder in the "Prompts" source

The --source / -s option filters results to a single named source when multiple sources are registered. The source is matched by its configured name or by owner/repo.

synap status

Show the sync status of every tracked file at a glance — similar to git status.

synap status

Output groups files into five states:

• Changed upstream — the remote file has a newer SHA than your local copy
• Missing locally — was pulled before but the local file has been deleted
• Not yet pulled — exists in the remote repo but hasn't been pulled yet
• Removed upstream — file was tracked but has been deleted from the remote repo
• Up to date — local file matches the remote SHA exactly

synap pull [name]

Download files from the remote repo to your local output directory. Shows a status preview and asks for confirmation before writing. If any tracked files have been modified locally since the last pull, the preview highlights them with a warning so you can decide whether to overwrite. Supports tab completion on the name argument.

synap pull                      # pull all files (with preview + confirm)
synap pull summarizer           # pull files matching "summarizer"
synap pull --interactive        # choose files from a checklist (includes Select / Deselect All)
synap pull --dry-run            # preview without writing
synap pull --force              # overwrite without prompting
synap pull --ref feat/v2        # pull from a specific branch
synap pull --ref v1.2.0         # pull from a tag
synap pull --ref a1b2c3d        # pull from a specific commit SHA
synap pull --retry-failed       # retry only files that failed in the last run

When multiple sources are registered, pull processes each one in sequence. The preview shows the source name as a label (e.g. [Agents]) and a progression counter (e.g. (1/3)) so you always know which source you're looking at. In interactive mode, deselecting all files or cancelling one source skips it and moves to the next — it no longer exits the entire process. A Select / Deselect All toggle appears at the top of every checklist: checking it selects all files if not all are selected, or clears all if they are.

synap diff [name]

Show a colored line-by-line diff of what has changed upstream versus your local files. Supports tab completion on the name argument.

synap diff             # diff all tracked files
synap diff summarizer  # diff files matching "summarizer"

synap update [name]

Pull only files whose upstream SHA has changed. Skips unchanged files entirely. If any tracked files have been modified locally since the last pull, the preview highlights them with a warning before overwriting. Supports tab completion on the name argument.

synap update                    # update all changed files (with preview + confirm)
synap update summarizer         # update files matching "summarizer"
synap update --interactive      # choose which changed files to update (includes Select / Deselect All)
synap update --force            # skip confirmation prompt

synap delete [name]

Delete tracked files from disk and remove their entries from the lockfile. Supports tab completion on the name argument.

synap delete                    # delete all tracked files
synap delete summarizer         # delete files matching "summarizer"
synap delete --dry-run          # preview without deleting
synap delete --force            # skip confirmation prompt

synap completion [shell]

Output or install shell tab completion. Supports bash, zsh, fish, and PowerShell (including 5.1). All shell scripts read directly from local cache files — no subprocess spawned on each tab press.

synap completion --install      # interactive install (auto-detects your shell)
synap completion powershell     # print the PowerShell script to stdout
synap completion bash           # print the bash script to stdout

synap register

Add one or more repositories to an existing synap.config.json. Automatically migrates a single-source config to the multi-source format if needed. Detects and skips duplicates — a duplicate is defined as the same repo and remotePath combination, so you can register the same repository multiple times with different remotePath values to pull from different subdirectories.

synap register                      # interactive — walk through prompts
synap register --from ./team.collection.json   # import from a local collection file
synap register --from org/repo/path/to/file.collection.json  # import from GitHub (shorthand)
synap register --from https://raw.githubusercontent.com/org/repo/main/agents.collection.json
synap register --from ./team.collection.json --yes  # skip localOutput confirmation prompts
synap register --from org/repo/shared.json --ref v2  # fetch from a specific branch/tag

The --from flag imports sources from a collection file — a JSON file containing a sources[] array (same schema as synap.config.json). This makes it easy to share a curated set of sources across teams or projects. See Collection files below for the format.

During import, SynapCLI:

• Skips sources already registered (same repo + remotePath + branch)
• Detects name conflicts and offers to rename or skip
• Backs up your existing config to synap.config.json.bak before merging
• Tags each imported source with _importedFrom for traceability

synap deregister

Remove a registered repository from synap.config.json. Presents a checklist of current sources to choose from. Cleans up orphaned lock entries automatically. Local files already pulled are not deleted — run synap delete separately if you want to remove them.

synap deregister

synap install <source>

Install files from a collection file — a curated set of individual files from one or more repos, hand-picked by an author. Unlike register --from (which imports repo-level sources), install downloads specific files directly.

synap install ./react-kit.collection.json          # local file
synap install org/repo/react-kit.collection.json    # GitHub shorthand
synap install --yes                                 # accept all defaults, no prompts
synap install --preset claude                       # override stored preset
synap install --dry-run                             # preview without writing

On first install, SynapCLI prompts you to choose a development system preset (GitHub Copilot, Claude Code, Gemini, Codex, or none). The preset remaps default output directories — e.g., .github/skills becomes .claude/skills for Claude users. The choice is saved to synap.config.json and never asked again.

Each file is tracked individually in the lockfile with a collection tag, and a _collection::Name definition entry stores the resolved path mappings for future updates.

synap collection create <name>

Author-side command. Reads your lockfile and lets you select tracked files to bundle into a shareable collection file.

synap collection create react-kit           # interactive — pick files, name, description
synap collection create react-kit --json    # output to stdout as JSON (for piping/CI)

Writes <name>.collection.json to the current directory. The file contains the selected files' repo, branch, path, and defaultOutput — ready for consumers to install with synap install.

Configuration

synap.config.json supports both a simple single-source format and a multi-source format.

Single source (simple)

{
  "repo": "acme-org/ai-agents",
  "branch": "main",
  "remotePath": "",
  "localOutput": "."
}

Multiple sources

{
  "sources": [
    {
      "name": "Agents",
      "repo": "acme-org/ai-agents",
      "branch": "main",
      "remotePath": "agents",
      "localOutput": ".",
      "include": ["**/*.md"],
      "exclude": ["**/test/**"]
    },
    {
      "name": "Prompts",
      "repo": "widgets-inc/prompt-library",
      "branch": "main",
      "remotePath": "prompts",
      "localOutput": "src/prompts"
    },
    {
      "name": "Shared agents (another project)",
      "repo": "acme-org/ai-agents",
      "branch": "main",
      "remotePath": "agents",
      "localOutput": "/home/you/other-project/.github/agents"
    }
  ],
  "postpull": "prettier --write ."
}

Config reference

| Field | Description | |---|---| | repo | GitHub repository as owner/repo | | branch | Branch, tag, or commit SHA (default: main) | | remotePath | Folder inside the repo to pull from (blank = repo root) | | localOutput | Local directory to write files into (default: .). Accepts relative paths (resolved from the project root) or absolute paths (e.g. C:\Users\you\other-project or /home/you/other-project) | | include | Glob patterns — only matching files are pulled | | exclude | Glob patterns — matching files are skipped | | postpull | Shell command run automatically after any pull or update | | sources | Array of the above for multi-source projects | | preset | Development system preset for collection installs (copilot, claude, gemini, codex, or none) | | _importedFrom | (Auto-set by register --from) Origin URL or file path of the collection the source was imported from |

Collection files

A collection file is a JSON file with a sources[] array — the same schema as synap.config.json minus project-level fields like postpull. Use collection files to share curated sets of sources with your team or the community.

{
  "sources": [
    {
      "name": "Claude Skills",
      "repo": "acme-org/ai-agents",
      "branch": "main",
      "remotePath": "skills",
      "localOutput": ".github/skills"
    },
    {
      "name": "Copilot Instructions",
      "repo": "acme-org/ai-agents",
      "branch": "main",
      "remotePath": "instructions",
      "localOutput": ".github"
    }
  ]
}

Import with synap register --from <path-or-url>. The --from flag accepts three formats:

| Format | Example | |---|---| | Local file path | ./team.collection.json | | GitHub shorthand | org/repo/path/to/file.collection.json | | Raw GitHub URL | https://raw.githubusercontent.com/org/repo/main/file.json |

Asset collection files

An asset collection file is a JSON file listing individual files (not entire repos). Created with synap collection create and consumed with synap install. This is asset-level sharing — a React expert can hand-pick the exact 7 files you need instead of pointing you at 3 repos.

{
  "name": "React Development Kit",
  "description": "Curated assets for React development",
  "assets": [
    {
      "repo": "acme/ai-agents",
      "branch": "main",
      "path": "skills/frontend-design/SKILL.md",
      "defaultOutput": ".github/skills"
    },
    {
      "repo": "acme/tools",
      "branch": "main",
      "path": "scripts/lint-components.py",
      "defaultOutput": "scripts"
    }
  ]
}

| Field | Description | |---|---| | name | Human-readable name for the collection | | description | (Optional) Short description | | assets[].repo | owner/repo | | assets[].branch | Branch, tag, or SHA | | assets[].path | Full path to the file within the repo | | assets[].defaultOutput | Creator's suggested local directory (remapped by preset on install) |

Lockfile

After every pull, SynapCLI writes synap.lock.json recording the exact commit SHA of each file. Keys are namespaced by repo to support multiple sources.

{
  "acme-org/ai-agents::agents/summarizer.md": {
    "sha": "a1b2c3d...",
    "ref": "main",
    "pulledAt": "2024-11-01T12:00:00.000Z"
  }
}

Files installed from a collection include a collection tag and the lockfile also stores a _collection::Name definition entry with the resolved path mappings:

{
  "acme/ai-agents::skills/SKILL.md": {
    "sha": "a1b2c3d...",
    "ref": "main",
    "pulledAt": "2026-04-15T12:00:00.000Z",
    "collection": "React Kit"
  },
  "_collection::React Kit": {
    "sha": "def456...",
    "ref": "main",
    "pulledAt": "2026-04-15T12:00:00.000Z",
    "origin": "org/repo/react-kit.collection.json",
    "pathOverrides": { ".github/skills": ".claude/skills" }
  }
}

Commit this file. It ensures reproducible pulls and powers status, diff, update, and delete.

Local Modification Detection

SynapCLI detects when you've edited a tracked file locally since the last pull. Before overwriting, both pull and update compute the Git blob SHA of your local file and compare it to the SHA stored in the lockfile. If they differ, the file is flagged as locally modified in the confirmation preview:

  ⚠ Locally modified (1):
    ! agents/summarizer.md → ./summarizer.md — local changes will be overwritten

This gives you a chance to back up your changes or cancel before they are replaced by the remote version.

• In interactive mode (--interactive), locally modified files are labeled in the checklist so you can deselect them individually. A Select / Deselect All toggle appears at the top of every checklist for quick bulk selection.
• With --force, all prompts are skipped and files are overwritten without warning — use with caution.

Tab Completion

SynapCLI supports tab completion for file names on pull, update, diff, and delete. Completions are read from a local cache file (~/.synap/completions.json) — no network call on every tab press.

The cache is populated automatically whenever you run synap init, synap register, synap install, synap list, synap pull, or synap update.

synap pull co<TAB>       # completes to matching file names
synap delete summ<TAB>   # same

Supported shells:

| Shell | Platform | Notes | |---|---|---| | zsh | Mac, Linux | Default shell on macOS Catalina (2019) and later | | bash | Mac, Linux, Windows | Default on older Macs and most Linux distros | | fish | Mac, Linux | | | PowerShell 5.1+ | Windows, Mac, Linux | Recommended shell for Windows users | | Git Bash | Windows | Ships with Git for Windows — runs real bash, so the bash completion script applies |

Not supported: Windows Command Prompt (cmd.exe) — Command Prompt has no custom completion API. It only supports basic file path completion built into the OS and cannot be extended by third-party tools. If you are on Windows, use PowerShell or Git Bash instead — both are available in VS Code's integrated terminal.

Git Bash note: When installing via synap completion --install, select bash. The script is appended to ~/.bashrc, and a ~/.bash_profile bridge is created automatically if none exists. If completions don't appear after restarting Git Bash and you already had a ~/.bash_profile before installing, add source ~/.bashrc to it manually.

Install:

synap completion --install   # auto-detects your shell and appends the script

Or print the script manually for a specific shell:

synap completion powershell >> $PROFILE
synap completion bash >> ~/.bashrc

CI/CD

Pass --ci to any command to enable CI mode:

• No interactive prompts
• Plain text output (no ANSI color codes)
• Strict failures — conflicts exit with a non-zero code instead of prompting

synap pull --ci --force
synap update --ci --force

Note on env: SynapCLI's own config file (synap.config.json) has no env block — the token is read from your OS environment or ~/.gitconfig. The env: keyword you'll see in the GitHub Actions workflow below is standard GitHub Actions syntax for passing a secret into a workflow step as an environment variable. They are unrelated — one is SynapCLI config, the other is GitHub Actions plumbing.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | General error | | 2 | Config error (missing or invalid synap.config.json) | | 3 | Auth error (invalid or missing token) | | 4 | Network error (GitHub API unreachable or 404) | | 5 | Conflict error (file conflict in CI mode without --force) |

GitHub Actions example

A ready-to-use workflow is included at templates/sync-agents.yml. Copy it into your project at .github/workflows/sync-agents.yml to enable automatic daily syncing. It runs on a daily schedule and commits any changed files back to your repository automatically.

Understanding secrets in GitHub Actions

${{ secrets.X }} is how a workflow accesses an encrypted value you have stored in GitHub. You set these once under Repository → Settings → Secrets and variables → Actions → New repository secret, and GitHub injects them securely at runtime — they are never visible in logs or to other users.

secrets.GITHUB_TOKEN is a special case — GitHub creates it automatically for every repository. You never have to set it up yourself. It is scoped to the repository the workflow is running in and expires when the workflow finishes.

Which token to use

The following examples all show the relevant step inside .github/workflows/sync-agents.yml.

Public agent repo — remove the env block entirely. No token needed:

- name: Pull latest agents and prompts
  run: synap pull --ci --force

Private agent repo in the same GitHub organization — the built-in token is scoped only to the repo the workflow runs in. You still need a PAT unless your organization has explicitly granted cross-repo token access in its settings. If cross-repo access is enabled, use the built-in token:

- name: Pull latest agents and prompts
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: synap pull --ci --force

Private agent repo in a different organization or personal account — the built-in token won't have access. Create a Personal Access Token (PAT) with Contents: Read-only on the agent repo, add it as a repository secret, then reference it by the secret name you chose:

- name: Pull latest agents and prompts
  env:
    GITHUB_TOKEN: ${{ secrets.AGENT_REPO_TOKEN }}
  run: synap pull --ci --force

Pulling from multiple private repos

SynapCLI reads a single GITHUB_TOKEN environment variable, so you cannot pass a different token per repo. The solution is to create one PAT and grant it Contents: Read-only access to each private repo individually when setting it up.

For example, if your synap.config.json pulls from both acme-org/ai-agents and widgets-inc/prompt-library:

1. Go to github.com/settings/tokens and create a new fine-grained PAT
2. Under Repository access, add each repo individually — they can be from different organizations, for example acme-org/ai-agents and widgets-inc/prompt-library. You must be a member of each org to grant access to its repos.
3. Under Permissions, set Contents to Read-only
4. Copy the generated token
5. In your project on GitHub, go to Settings → Secrets and variables → Actions → New repository secret, name it SYNAP_TOKEN, and paste the token
6. Reference it in your workflow:

- name: Pull latest agents and prompts
  env:
    GITHUB_TOKEN: ${{ secrets.SYNAP_TOKEN }}
  run: synap pull --ci --force

This one token covers all repos listed in your synap.config.json, so no additional secrets are needed.

Contributing

Interested in contributing? See CONTRIBUTING.md for setup instructions, project structure, and how to submit a pull request.

How SynapCLI Compares

vs GitHub Copilot CLI Plugins

Copilot CLI plugins are installable packages that bundle agents, skills, hooks, and MCP/LSP server configs into a single unit. They're distributed through marketplaces (which are themselves GitHub repos) and installed with a built-in command. If your team standardises on Copilot CLI, plugins are the native way to share capabilities.

Under the hood, though, plugins are just files and folders in a GitHub repository — *.agent.md files, SKILL.md files, hooks.json, .mcp.json, and so on. That means SynapCLI can pull them too. If you want to cherry-pick specific agents or skills from a plugin repo without installing the full package, or mix assets from plugin repos with files from non-plugin repos (coding standards, prompt libraries, CI templates), SynapCLI gives you that flexibility. You can also use synap status and synap diff to track exactly which versions of those files you're running — something the plugin system doesn't expose.

The two tools are complementary: use plugins when you want the full curated package with marketplace discovery, and use SynapCLI when you want fine-grained file-level control, cross-repo aggregation, or lockfile-based change tracking.

vs Git Submodules

Git submodules are the closest built-in alternative — they embed one repo inside another and pin to a specific commit. On paper they sound similar but in practice they are cumbersome. Cloning a repo with submodules requires git clone --recurse-submodules or a separate git submodule update --init, and new team members forget this constantly. Updating a submodule requires navigating into the submodule directory, pulling, then committing the parent repo to record the new SHA. They also bring the entire repository history rather than just the files you need, and CI pipelines require extra configuration to handle them.

SynapCLI is file-focused rather than repo-focused. You pull exactly the files you want, they land as normal files in your project with no git entanglement, and updating is a single command. The lockfile gives you the same reproducibility guarantee as a pinned submodule SHA, without the complexity.

vs Copier / Cookiecutter

These Python-based scaffolding tools pull templates from a GitHub repo and stamp them into a new project. Copier in particular has an update command that can re-apply upstream template changes, which is conceptually similar to synap update. The differences are that they are Python-based, template-centric with variable substitution as a first-class feature, and designed for one-time project creation rather than ongoing file sync across many existing projects.

vs npm packages

The most common enterprise approach is to publish shared files as a versioned npm package and install them. This is robust and integrates with existing tooling, but it adds a publish step every time something changes, requires an npm account or private registry, and files end up buried in node_modules rather than sitting in your project where you can read and edit them directly.

vs Turborepo / Nx

Monorepo tools solve a related problem — sharing code across packages — but they require everyone to be in the same monorepo. This doesn't work when you want to share agents and prompts across completely separate client projects maintained by different teams.

vs GitHub Actions file sync

Some teams use GitHub Actions to automatically push files from a central repo into target repos on every commit. This works well for CI but has no local developer workflow — you cannot run it from your terminal, preview changes, or selectively pull individual files.

Where SynapCLI fits best

SynapCLI is most valuable in these situations:

AI-assisted development teams — sharing a central library of agent definitions, system prompts, copilot instructions, scripts, resources, and other AI model assets across multiple projects. As these files evolve, synap update keeps every project in sync without manual copying.

Design system and standards distribution — distributing coding standards, architecture guidelines, and documentation templates from a central source of truth into many downstream projects. The lockfile ensures every project can be audited for which version of each standard it is running.

Cross-project configuration sync — sharing ESLint configs, TypeScript configs, CI workflow templates, or any other boilerplate files that need to stay consistent across a portfolio of projects, with the ability to opt into updates on your own schedule rather than being forced by a package version bump.

Teams without monorepo infrastructure — getting the benefits of shared, versioned files without the overhead of setting up and maintaining Turborepo, Nx, or a private npm registry.