CLI Usage Guide

The Synapse SDK provides a powerful interactive CLI for managing your development workflow, from configuration to plugin development and code editing.

Getting Started

Launch the interactive CLI:

synapse

Or run specific commands directly:

# Start development tools immediately
synapse --dev-tools

# Show help
synapse --help

When you run synapse, you'll see the main menu:

🚀 Synapse SDK
Select an option:
  🌐 Run Dev Tools
  💻 Open Code-Server IDE
  ⚙️  Configuration
  🔌 Plugin Management
  🚪 Exit

🌐 Run Dev Tools

Launches the Synapse development tools dashboard with:

Interactive UI: Web-based dashboard for managing agents and jobs
Real-time Monitoring: Live view of agent status and job execution
Plugin Management: Upload, test, and manage plugins through the UI

Usage

# Launch dev tools from CLI menu
synapse

# Or start directly
synapse --dev-tools

💻 Open Code-Server IDE

Opens a web-based VS Code environment for plugin development. Supports both agent-based and local code-server instances.

Agent Code-Server

Connect to a remote code-server running on an agent:

Automatic Setup: Synapse configures the workspace and installs dependencies
Plugin Encryption: Local plugin code is encrypted and securely transferred
Workspace Sync: Your local project is available in the agent environment

Local Code-Server

Launch a local code-server instance:

Port Detection: Automatically reads port from ~/.config/code-server/config.yaml
Folder Parameter: Opens with correct workspace directory
Browser Integration: Automatically opens browser with proper URL

Usage Examples

# Interactive menu (recommended)
synapse
# Select "💻 Open Code-Server IDE"

# Direct command
synapse code-server

# With specific options
synapse code-server --agent my-agent --workspace /path/to/project

# Don't open browser automatically
synapse code-server --no-open-browser

Code-Server Options

Option	Description	Default
`--agent`	Specific agent ID to use	Current agent or prompt
`--workspace`	Project directory path	Current directory
`--open-browser/--no-open-browser`	Open browser automatically	`--open-browser`

Local Code-Server Installation

If code-server isn't installed locally, the CLI provides installation instructions:

# Recommended: Install script
curl -fsSL https://code-server.dev/install.sh | sh

# Using npm
npm install -g code-server

# Using yarn
yarn global add code-server

For more options, visit: https://coder.com/docs/code-server/latest/install

⚙️ Configuration

Interactive configuration wizard for setting up:

Backend Connection: Configure API endpoints and authentication
Agent Selection: Choose and configure development agents
Token Management: Manage access tokens and authentication

Configuration Files

Synapse stores configuration in:

Backend Config: ~/.synapse/devtools.yaml
Agent Config: ~/.synapse/devtools.yaml (agent section)
Code-Server Config: ~/.config/code-server/config.yaml

🔌 Plugin Management

Comprehensive plugin development and management tools:

Create New Plugin

synapse
# Select "🔌 Plugin Management" → "Create new plugin"

Interactive wizard creates:

Plugin directory structure
Configuration files (config.yaml)
Example plugin code
Requirements and dependencies

Run Plugin Locally

Test plugins in different environments:

# Script execution (local)
synapse plugin run my_action '{"param": "value"}' --run-by script

# Agent execution (remote)
synapse plugin run my_action '{"param": "value"}' --run-by agent

# Backend execution (cloud)
synapse plugin run my_action '{"param": "value"}' --run-by backend

Publish Plugin

Deploy plugins to your Synapse backend:

synapse
# Select "🔌 Plugin Management" → "Publish plugin"

Options:

Debug Mode: Test deployment with verbose logging
Production Mode: Deploy for live use

Command Reference

Main Commands

# Interactive CLI (main menu)
synapse

# Development tools
synapse --dev-tools

# Direct commands
synapse config         # Configuration wizard
synapse devtools       # Development dashboard
synapse code-server    # Code editing environment
synapse plugin         # Plugin management

Code-Server Command

synapse code-server [OPTIONS]

Options:
  --agent TEXT                    Agent name or ID
  --open-browser / --no-open-browser
                                  Open in browser [default: open-browser]
  --workspace TEXT                Workspace directory path (defaults to current directory)
  --help                          Show this message and exit.

Plugin Commands

# Create plugin
synapse plugin create

# Run plugin
synapse plugin run ACTION PARAMS [OPTIONS]

# Publish plugin  
synapse plugin publish [OPTIONS]

Tips & Best Practices

Code-Server Development

Plugin Detection: When opening code-server, Synapse automatically detects if your workspace contains a plugin and encrypts it for secure transfer to agents.
Workspace Paths: Agent workspaces typically use /home/coder/workspace - this is normal for containerized environments.
Port Configuration: Local code-server port is read from your config file, defaulting to 8070 if not configured.

Configuration Management

Token Security: Store API tokens securely and rotate them regularly
Agent Selection: Use descriptive agent names to identify their purpose
Backend URLs: Ensure backend URLs are accessible from your development environment

Plugin Development

Local Testing: Always test plugins locally with --run-by script before deploying
Debug Mode: Use debug mode for initial deployments to catch issues early
Version Control: Use git to track plugin changes and manage versions

Troubleshooting

Code-Server Issues

Problem: "Code-server is not available"

Solution: Ensure the agent has code-server support enabled

Problem: Browser doesn't open automatically

Solution: Manually copy the provided URL to your browser

Problem: Wrong port displayed

Solution: Check ~/.config/code-server/config.yaml for correct port configuration

Configuration Issues

Problem: "No backend configured"

Solution: Run synapse config to set up backend connection

Problem: "Invalid token (401)"

Solution: Generate a new API token and update configuration

Problem: "Connection timeout"

Solution: Check network connectivity and backend URL accessibility

Plugin Issues

Problem: Plugin not detected in workspace

Solution: Ensure your directory has a valid config.yaml file

Problem: Plugin execution fails

Solution: Check plugin dependencies and syntax, test locally first

For more troubleshooting help, see the Troubleshooting Guide.

Getting Started​

Main Menu Options​

🌐 Run Dev Tools​

Usage​

💻 Open Code-Server IDE​

Agent Code-Server​

Local Code-Server​

Usage Examples​

Code-Server Options​

Local Code-Server Installation​

⚙️ Configuration​

Configuration Files​

🔌 Plugin Management​

Create New Plugin​

Run Plugin Locally​

Publish Plugin​

Command Reference​

Main Commands​

Code-Server Command​

Plugin Commands​

Tips & Best Practices​

Code-Server Development​

Configuration Management​

Plugin Development​

Troubleshooting​

Code-Server Issues​

Configuration Issues​

Plugin Issues​