Synapse CLI

A powerful, feature-rich command-line interface for the Synapse framework. Built with pure Node.js APIs and zero external dependencies for core functionality.

Features

• 🚀 Project Scaffolding - Create new Synapse projects with multiple templates
• 📦 Package Management - Add packages and features with intelligent dependency resolution
• 🔧 Development Server - Start development servers with hot reload and file watching
• 🎨 Rich UI - Beautiful, colorful output with progress indicators and interactive prompts
• 🔌 Plugin System - Extensible architecture with plugin support
• 🛠️ Zero Dependencies - Core functionality uses only built-in Node.js APIs
• ⚡ Fast Startup - Optimized for speed with lazy loading and caching
• 🎯 Type Safe - Full TypeScript support with comprehensive type definitions

Installation

Global Installation

# Using Bun (recommended)
bun install -g @maybenoobish/synapse-cli

# Using npm
npm install -g @maybenoobish/synapse-cli

# Using pnpm
pnpm install -g @maybenoobish/synapse-cli

# Using yarn
yarn global add @maybenoobish/synapse-cli

Local Installation

# Using Bun
bun add -D @maybenoobish/synapse-cli

# Using npm
npm install -D @maybenoobish/synapse-cli

# Using pnpm
pnpm add -D @maybenoobish/synapse-cli

# Using yarn
yarn add -D @maybenoobish/synapse-cli

Quick Start

Create a New Project

# Create a basic project
synapse create my-app

# Create with specific template
synapse create my-app --template full

# Create with custom configuration
synapse create my-app --template minimal --package-manager npm --no-git

Start Development

# Start development server
synapse dev

# Start with custom port
synapse dev --port 3001

# Start with HTTPS
synapse dev --https --open

Add Features

# Add a package
synapse add @maybenoobish/synapse-ui

# Add a feature with interactive setup
synapse add auth --interactive

# Add as dev dependency
synapse add typescript --dev

Commands

synapse create <name>

Create a new Synapse project with the specified name.

Options:

• --template, -t - Project template (basic, full, minimal, api)
• --package-manager, -p - Package manager (bun, npm, pnpm, yarn)
• --no-git - Skip Git initialization
• --no-install - Skip dependency installation
• --yes, -y - Skip confirmation prompts
• --author - Project author
• --description - Project description
• --license - Project license

Examples:

synapse create my-app
synapse create my-app --template full --package-manager npm
synapse create my-app --template minimal --no-git --yes

synapse add <package>

Add a package or feature to your project.

Options:

• --dev, -D - Add as dev dependency
• --version, -v - Package version
• --interactive, -i - Interactive mode
• --provider - Provider for feature packages
• --config - Configuration file path
• --yes, -y - Skip confirmation prompts

Examples:

synapse add @synapse/ui
synapse add auth --provider auth0 --interactive
synapse add typescript --dev --version ^5.0.0

synapse dev

Start the development server.

Options:

• --port, -p - Port number (default: 3000)
• --host, -h - Host address (default: localhost)
• --https - Enable HTTPS
• --open, -o - Open browser automatically
• --watch, -w - Watch for file changes
• --hot-reload - Enable hot module replacement
• --sourcemap - Generate source maps
• --debug - Enable debug mode
• --verbose, -v - Enable verbose output

Examples:

synapse dev
synapse dev --port 3001 --host 0.0.0.0
synapse dev --https --open --debug

synapse build

Build the project for production.

Options:

• --target - Build target (browser, node, edge)
• --minify - Enable minification
• --sourcemap - Generate source maps
• --splitting - Enable code splitting
• --outdir - Output directory
• --watch - Watch mode

Examples:

synapse build
synapse build --target browser --minify
synapse build --watch --sourcemap

synapse test

Run tests using Bun's test runner.

Options:

• --watch - Watch mode
• --coverage - Generate coverage report
• --parallel - Run tests in parallel
• --timeout - Test timeout
• --reporter - Test reporter

Examples:

synapse test
synapse test --watch --coverage
synapse test --parallel --timeout 10000

synapse deploy <platform>

Deploy the application to a platform.

Options:

• --config - Deployment configuration
• --env - Environment variables
• --build - Build before deploy
• --preview - Preview deployment

Examples:

synapse deploy vercel
synapse deploy netlify --config netlify.toml
synapse deploy cloudflare --env production

Project Templates

Basic Template

A minimal Synapse project with essential files and configuration.

my-app/
├── src/
│   ├── index.ts
│   └── app.ts
├── package.json
├── tsconfig.json
├── synapse.config.ts
└── README.md

Full Template

A complete Synapse project with all features and examples.

my-app/
├── src/
│   ├── components/
│   ├── pages/
│   ├── utils/
│   ├── types/
│   ├── index.ts
│   └── app.ts
├── public/
│   └── index.html
├── package.json
├── tsconfig.json
├── synapse.config.ts
└── README.md

Minimal Template

A bare-bones project for advanced users.

my-app/
├── src/
│   └── index.ts
├── package.json
└── README.md

API Template

A backend-only project for API development.

my-app/
├── src/
│   ├── routes/
│   ├── middleware/
│   ├── models/
│   └── index.ts
├── package.json
└── README.md

Configuration

synapse.config.ts

The main configuration file for your Synapse project.

import type { CLIConfig } from '@maybenoobish/synapse-cli';

export default {
  project: {
    name: 'my-synapse-app',
    version: '1.0.0',
    description: 'A Synapse application',
    author: 'Developer',
    license: 'MIT'
  },
  build: {
    target: 'browser',
    minify: true,
    sourcemap: true,
    splitting: true
  },
  dev: {
    port: 3000,
    host: 'localhost',
    https: false,
    open: true
  },
  deploy: {
    platform: 'vercel',
    config: {}
  },
  plugins: []
} satisfies CLIConfig;

Environment Variables

The CLI respects the following environment variables:

• SYNAPSE_PORT - Development server port
• SYNAPSE_HOST - Development server host
• SYNAPSE_HTTPS - Enable HTTPS
• SYNAPSE_OPEN - Open browser automatically
• SYNAPSE_TARGET - Build target
• SYNAPSE_MINIFY - Enable minification
• SYNAPSE_SOURCEMAP - Generate source maps
• SYNAPSE_PLATFORM - Deploy platform
• SYNAPSE_DEBUG - Enable debug mode
• SYNAPSE_VERBOSE - Enable verbose output

Plugin System

The Synapse CLI supports a powerful plugin system for extending functionality.

Creating a Plugin

// my-plugin.ts
import type { Plugin, PluginAPI } from '@synapse/cli';

export const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',
  hooks: {
    beforeCommand: async (command, args, flags) => {
      console.log(`Running command: ${command}`);
    },
    afterCommand: async (command, args, flags, result) => {
      console.log(`Command completed: ${command}`);
    }
  }
};

Plugin Hooks

• beforeCommand - Execute before any command
• afterCommand - Execute after any command
• onError - Handle errors
• onConfig - Modify configuration
• onInit - Initialize plugin
• onBuild - Modify build process
• onDeploy - Modify deployment

Plugin API

The plugin API provides access to CLI utilities:

interface PluginAPI {
  registerCommand: (command: CLICommand) => void;
  unregisterCommand: (name: string) => void;
  getConfig: () => CLIConfig;
  setConfig: (config: Partial<CLIConfig>) => void;
  getContext: () => CLIContext;
  logger: Logger;
  ui: UIComponents;
  fs: FileSystemUtils;
}

Advanced Usage

Custom Commands

You can register custom commands programmatically:

import { CommandRegistry } from '@synapse/cli';

const registry = new CommandRegistry();

registry.register({
  name: 'custom',
  description: 'Custom command',
  handler: async (args, flags) => {
    console.log('Custom command executed');
  }
});

Error Handling

The CLI provides comprehensive error handling:

import { ErrorHandler, SynapseCLIError } from '@synapse/cli';

try {
  // Your code
} catch (error) {
  if (error instanceof SynapseCLIError) {
    console.error(`CLI Error: ${error.message}`);
    console.error(`Suggestions: ${error.suggestions.join(', ')}`);
  } else {
    ErrorHandler.getInstance().handle(error);
  }
}

UI Components

Use the built-in UI components for rich terminal output:

import { Logger, Colors, Spinner, Table, Box, Prompt } from '@synapse/cli';

// Logging
Logger.info('Information message');
Logger.success('Success message');
Logger.warning('Warning message');
Logger.error('Error message');

// Spinner
const spinner = new Spinner('Loading...');
spinner.start();
// ... do work
spinner.success('Completed!');

// Table
const table = new Table(['Name', 'Value']);
table.addRow(['key1', 'value1']);
table.addRow(['key2', 'value2']);
table.render();

// Box
Box.render('Content', { title: 'Title', style: 'rounded' });

// Prompts
const name = await Prompt.input('Enter your name');
const choice = await Prompt.select('Choose option', ['option1', 'option2']);
const confirmed = await Prompt.confirm('Are you sure?');

Performance

The Synapse CLI is optimized for performance:

• Fast Startup - < 100ms startup time
• Lazy Loading - Commands are loaded only when needed
• Caching - Configuration and context are cached
• Parallel Operations - Multiple operations run concurrently
• Minimal Dependencies - Zero external dependencies for core functionality

Troubleshooting

Common Issues

Command not found

# Make sure the CLI is installed globally
bun install -g @synapse/cli

# Or use npx
npx @synapse/cli create my-app

Permission denied

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# Or use a different package manager
bun install -g @synapse/cli

Port already in use

# Use a different port
synapse dev --port 3001

Build failures

# Enable debug mode
synapse build --debug

# Check TypeScript configuration
synapse build --verbose

Debug Mode

Enable debug mode for detailed logging:

synapse dev --debug
synapse build --debug
synapse deploy --debug

Verbose Output

Enable verbose output for more information:

synapse dev --verbose
synapse build --verbose

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/synapse-framework/cli.git
cd cli

# Install dependencies
bun install

# Run tests
bun test

# Build the CLI
bun run build

# Test locally
bun run dev create test-app

Running Tests

# Run all tests
bun test

# Run specific test file
bun test src/core/parser.test.ts

# Run tests with coverage
bun test --coverage

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Changelog

See CHANGELOG.md for a list of changes and updates.

Made with ❤️ by the Synapse team