npm package: @smartmarbles/synapcli
Description: Sync files from a GitHub repository into any project — built for AI-assisted development teams sharing agent definitions, system prompts, instructions, coding standards, scripts, resources, and any other AI assets across a portfolio of projects.
Author: SmartMarbles.com
Latest version: 1.0.5

<h1 align="center">
	<br>
	<img width="500" src="assets/synapcli_logo1.png" alt="Synap CLI logo with half brain half circuit wiring">
	<br>
	<br>
</h1>

# SynapCLI

[![npm version](https://img.shields.io/npm/v/@smartmarbles/synapcli.svg)](https://www.npmjs.com/package/@smartmarbles/synapcli)
[![npm downloads](https://img.shields.io/npm/dm/@smartmarbles/synapcli.svg)](https://www.npmjs.com/package/@smartmarbles/synapcli)
[![CI](https://github.com/smartmarbles/synapcli/actions/workflows/ci.yml/badge.svg)](https://github.com/smartmarbles/synapcli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/node/v/@smartmarbles/synapcli.svg)](https://nodejs.org)

A professional 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 diffing, tab completion, and more.

---

## 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:
```bash
npm install -g synapcli
synap --version
```

**Or use via npx** without installing:
```bash
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**
```bash
# Mac/Linux
export GITHUB_TOKEN=ghp_yourtoken

# Windows PowerShell
$env:GITHUB_TOKEN="ghp_yourtoken"
```

**2. `~/.gitconfig` (recommended — persists across sessions)**
```bash
git config --global synapcli.githubToken ghp_yourtoken
```

Or add it manually to `~/.gitconfig`:
```ini
[synapcli]
    githubToken = ghp_yourtoken
```

Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens). For fine-grained tokens, grant **Contents: Read-only** on the target repository.

---

## Quick Start

```bash
# 1. Bootstrap config in your project (supports multiple repos from the start)
synap init

# 2. Validate your entire setup
synap doctor

# 3. Add another repository later
synap register

# 4. Remove a repository
synap deregister

# 5. Browse available files in the remote repo
synap list

# 5b. List files under a specific subfolder
synap list skills

# 6. See the sync status of all tracked files
synap status

# 7. Pull everything down
synap pull

# 8. Pull a specific file at a specific ref (branch, tag, or commit SHA)
synap pull --ref v1.2.0 copilot-instructions<TAB>

# 9. Pull interactively — choose files from a checklist
synap pull --interactive

# 10. See what changed upstream vs your local files
synap diff

# 11. Pull only files that have changed
synap update

# 12. Delete a tracked file
synap delete summarizer

# 13. Install shell tab completion (only needed if skipped during init)
synap completion --install
```

> **Looking for a real-world multi-source example?** See [EXAMPLES.md](https://github.com/smartmarbles/synapcli/blob/main/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 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).

```bash
synap doctor
```

---

### `synap list [path]`
List all files available in the configured remote repository. Optionally scope the listing to a subdirectory by passing a path argument — this is appended to the configured `remotePath`.

```bash
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`.

```bash
synap status
```

Output groups files into four 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
- **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.

```bash
synap pull                      # pull all files (with preview + confirm)
synap pull summarizer           # pull files matching "summarizer"
synap pull --interactive        # choose files from a checklist
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
```

---

### `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.

```bash
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.

```bash
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
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.

```bash
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). The PowerShell script reads directly from the local cache file with no subprocess. Bash, zsh, and fish use a lightweight `synap --get-completions` subprocess call.

```bash
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.

```bash
synap register
```

---

### `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.

```bash
synap deregister
```

---

## Configuration

`synap.config.json` supports both a simple single-source format and a multi-source format.

### Single source (simple)

```json
{
  "repo": "acme-org/ai-agents",
  "branch": "main",
  "remotePath": "",
  "localOutput": "."
}
```

### Multiple sources

```json
{
  "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 |

---

## 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.

```json
{
  "acme-org/ai-agents::agents/summarizer.md": {
    "sha": "a1b2c3d...",
    "ref": "main",
    "pulledAt": "2024-11-01T12:00:00.000Z"
  }
}
```

**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.
- 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 list`, `synap pull`, or `synap update`.

```bash
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 will be appended to `~/.bashrc`. If completions don't appear after restarting Git Bash, add `source ~/.bashrc` to your `~/.bash_profile` — Git Bash sometimes loads `.bash_profile` instead of `.bashrc` on startup.

**Install:**
```bash
synap completion --install   # auto-detects your shell and appends the script
```

Or print the script manually for a specific shell:
```bash
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

```bash
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:
```yaml
- 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:
```yaml
- 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:
```yaml
- 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](https://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:

```yaml
- 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.

---

## How SynapCLI Compares

### 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.


---

## Contributing

Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, project structure, and how to submit a pull request.