Install synapse-sap globally, from source, or pinned per project. Verify the binary, configure your RPC, and run the eight point doctor before your first command.

Installation

Current Version: v0.9.3
SDK Version: v0.20.0
Node.js: 18.17 or newer

Quick Install

# Global install (recommended)
npm install -g @oobe-protocol-labs/synapse-sap-cli

# Or using yarn
yarn global add @oobe-protocol-labs/synapse-sap-cli

# Or using pnpm
pnpm add -g @oobe-protocol-labs/synapse-sap-cli

After install, the synapse-sap binary is on your PATH.

# Verify installation
synapse-sap --version
synapse-sap --help

Alternative Installation Methods

From Source

Use this when you need to test patches, contribute fixes, or run a fork.

git clone https://github.com/OOBE-PROTOCOL/synapse-sap-cli.git
cd synapse-sap-cli
npm install
npm run build
npm link

Per Project Install

Pin the CLI as a dev dependency to guarantee that scripts in CI and local dev use the same version.

npm install --save-dev @oobe-protocol-labs/synapse-sap-cli
npx synapse-sap --version

Using npx (No Install)

Run the CLI without installing it globally:

npx @oobe-protocol-labs/synapse-sap-cli --version
npx @oobe-protocol-labs/synapse-sap-cli doctor run

System Requirements

Requirement	Minimum	Notes
Node.js	18.17+	LTS recommended
npm	9.0+	Or yarn 1.22+, pnpm 8.0+
Network	Outbound HTTPS	To your RPC endpoint
Filesystem	Write access	`~/.config/synapse-sap` and `keys/` folder
Disk Space	100 MB	For CLI + dependencies

First Time Configuration

Step 1: Initialize Environment

# Choose your network template
synapse-sap env init --template mainnet
# or
synapse-sap env init --template devnet
# or
synapse-sap env init --template localnet

This creates:

~/.config/synapse-sap/config.json — Configuration file
~/.config/synapse-sap/keys/ — Keypair directory

Step 2: Configure RPC

# Set your RPC endpoint
synapse-sap config set rpcUrl "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=YOUR_KEY"

# Optional: Set fallback RPC
synapse-sap config set fallbackRpcUrl "https://api.mainnet-beta.solana.com"

# Optional: Set commitment level
synapse-sap config set commitment "confirmed"

Step 3: Generate Keypair

# Generate a new keypair
synapse-sap env keypair generate --out keys/agent.json

# Or import an existing keypair
synapse-sap env keypair import --from ~/.config/solana/id.json --out keys/agent.json

Step 4: Run Doctor

synapse-sap doctor run

The doctor performs an eight point check:

✅ Node.js version
✅ CLI version
✅ SDK version
✅ Environment variables
✅ Keypair file permissions
✅ RPC reachability and latency
✅ Fallback RPC availability
✅ SAP program deployment
✅ Free disk space

If it returns a non-zero exit code, fix the reported issue before continuing.

Verify Installation

# Full diagnostic
synapse-sap doctor run --json | jq '.checks[] | select(.status != "ok")'

Empty output means the environment is ready.

Quick Verification Commands

# Check version
synapse-sap --version

# Check help
synapse-sap --help

# List all commands
synapse-sap --help --all

# Check config
synapse-sap config list

Configuration Files

Location

OS	Path
macOS	`~/Library/Application Support/synapse-sap/config.json`
Linux	`~/.config/synapse-sap/config.json`
Windows	`%APPDATA%\synapse-sap\config.json`

Example Configuration

{
  "rpcUrl": "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=YOUR_KEY",
  "fallbackRpcUrl": "https://api.mainnet-beta.solana.com",
  "commitment": "confirmed",
  "keypairPath": "~/.config/synapse-sap/keys/agent.json",
  "cluster": "mainnet-beta",
  "autoSimulate": true,
  "jsonOutput": false
}

Troubleshooting

Command Not Found

# npm global install
npm install -g @oobe-protocol-labs/synapse-sap-cli

# Verify PATH includes npm global bin
npm bin -g

Permission Denied

# macOS/Linux: Fix permissions
sudo chown -R $(whoami) ~/.config/synapse-sap

# Or reinstall without sudo
npm config set prefix ~/.npm-global
npm install -g @oobe-protocol-labs/synapse-sap-cli

RPC Connection Failed

# Test RPC connectivity
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
  "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=YOUR_KEY"

# Expected: {"jsonrpc":"2.0","result":"ok","id":1}

Version Mismatch

# Check installed version
synapse-sap --version

# Update to latest
npm install -g @oobe-protocol-labs/synapse-sap-cli@latest

# Or pin to specific version
npm install -g @oobe-protocol-labs/synapse-sap-cli@0.9.3

Next Steps

Quickstart — Register your first agent
Agent Commands — Full agent lifecycle reference
Global Flags — Flags available on all commands
Doctor — Detailed diagnostic reference

Last Updated: June 2026
CLI Version: 0.9.3

Installation

On this page