Relay CLI

The official command-line interface for the Relay SMS platform, featuring integrated SMS development tools.

Installation

npm install -g @relay-works/cli

Quick Start

# Authenticate with Relay
relay login

# Generate configuration file
relay config init

# Start local development environment
relay dev

# Check status of development servers
relay status

SMS Development Integration

The Relay CLI includes seamless integration with sms-dev, a local SMS development server that acts as "Mailtrap for SMS" - allowing you to test SMS functionality without sending real messages.

Basic Usage

# Start development environment (includes sms-dev + UI)
relay dev

# Start with custom webhook URL
relay dev --webhook-url http://localhost:3000/webhook

# Start API only (no virtual phone UI)
relay dev --no-ui

# Start with custom ports
relay dev --api-port 4001 --ui-port 4000

Configuration

Create a relay.json file in your project root:

relay config init

Example relay.json:

{
  "project": {
    "name": "My SMS App",
    "environment": "development"
  },
  "smsDev": {
    "apiPort": 4001,
    "uiPort": 4000,
    "webhookUrl": "http://localhost:3000/webhook",
    "verbose": false,
    "startUI": true
  }
}

Direct SMS-Dev Commands

Access sms-dev functionality directly through the Relay CLI:

# Show all available sms-dev commands
relay sms-dev

# Mock phone management
relay sms-dev mock-phone create --phone +1234567890 --name "Test User"
relay sms-dev mock-phone list
relay sms-dev mock-phone delete --phone +1234567890

# Conversation flows
relay sms-dev flow create --name "Welcome Flow"
relay sms-dev flow list
relay sms-dev flow execute --flow-id flow_123 --phone +1234567890

# Data export
relay sms-dev export messages --format json --output messages.json
relay sms-dev export conversations --format csv

# Performance testing
relay sms-dev perf stats
relay sms-dev perf load-test --messages 100 --users 5

# Server management
relay sms-dev status
relay sms-dev stop

Commands

Core Commands

• relay login - Authenticate with Relay platform
• relay logout - Sign out of your account
• relay status - Check development environment status
• relay open - Open Relay dashboard in browser

Development Commands

• relay dev - Start local development environment with sms-dev
• relay config [init|show] - Manage configuration
• relay sms-dev [command] - Access SMS development tools
• relay webhooks - Forward webhooks to local server
• relay logs - Tail production logs
• relay env - Pull environment variables

Project Management

• relay init - Initialize new Relay project

Configuration Priority

Configuration is loaded in this order (later values override earlier ones):

1. relay.json
2. relay.config.json
3. .relayrc
4. .relayrc.json
5. Environment variables
6. Command-line options

Environment Variables

• RELAY_API_URL - Relay API base URL
• SMS_DEV_API_PORT - SMS dev server API port
• SMS_DEV_UI_PORT - SMS dev server UI port
• SMS_DEV_WEBHOOK_URL - Webhook URL for testing
• SMS_DEV_VERBOSE=true - Enable verbose logging
• SMS_DEV_NO_UI=true - Disable UI server

Development Workflow

1. Setup: relay login and relay config init
2. Development: relay dev starts local SMS development environment
3. Testing: Use virtual phone UI at http://localhost:4000
4. API Testing: Point your app to http://localhost:4001
5. Production: Deploy with confidence knowing SMS works locally

Learn More

• Relay Platform
• SMS-Dev Tool
• Documentation

Support

• GitHub Issues: relay-works/relay-cli
• Documentation: docs.relay.works
• Support: [email protected]

Local Development (Contributing)

To run the CLI locally from source (e.g., within this repo):

1. Build the package:

   npm run build

2. Link globally:

   npm link

3. Run: You can now use relay command anywhere on your system, pointing to your local source.

   relay --version