sms-dev

Configuration

Configuration Guide

Learn how to configure sms-dev using CLI arguments, configuration files, and environment variables.

Configuration Precedence

sms-dev loads configuration from multiple sources with the following precedence (highest to lowest):

1

CLI Arguments

Flags passed directly to commands

sms-dev start --api-port 4002
2

Configuration Files

JavaScript or JSON config files

sms-dev.config.js
3

Environment Variables

System environment variables

SMS_DEV_API_PORT=4002
4

Default Values

Built-in defaults when no other configuration is found

apiPort: 4001, uiPort: 4000

Configuration Resolution

Higher precedence values override lower ones. For example, --api-port 4002 will override both environment variables and config file settings.

Quick Start

The fastest way to get started is with CLI arguments for simple configurations:

Basic Usage

sms-dev start

Starts with defaults: API on port 4001, UI on port 4000

Custom Ports

sms-dev start --api-port 5001 --ui-port 5000

Use custom ports for both API and UI servers

With Webhook URL

sms-dev start --webhook-url http://localhost:3000/webhook/sms

Forward SMS replies to your application's webhook endpoint

CLI Arguments

CLI arguments have the highest precedence and override all other configuration sources.

Available Arguments

ArgumentShortTypeDescription
--config-cstringConfiguration file path
--api-port-pnumberAPI server port
--ui-port-unumberUI server port
--webhook-url-stringWebhook URL for testing
--no-ui-booleanStart only API server
--verbose-booleanEnable verbose logging
--show-config-booleanShow config and exit

Configuration Files

Configuration files provide a persistent way to configure sms-dev. Multiple file formats are supported.

File Discovery Order

sms-dev looks for configuration files in this order:

  1. 1sms-dev.config.js
  2. 2sms-dev.config.json
  3. 3.smsdevrc (JSON format)

JavaScript Configuration

Most flexible option with full JavaScript support:

// sms-dev.config.js
module.exports = {
  // Server configuration
  apiPort: 4001,
  uiPort: 4000,
  
  // Start UI server
  startUI: true,
  
  // Webhook configuration
  webhookUrl: 'http://localhost:3000/webhook/sms',
  
  // CORS configuration
  cors: {
    enabled: true,
    origins: ['http://localhost:3000', 'http://localhost:3001']
  },
  
  // Logging configuration
  logging: {
    enabled: true,
    level: 'info' // 'debug' | 'info' | 'warn' | 'error'
  },
  
  // Development mode
  verbose: false
}

JSON Configuration

Simple JSON format for basic configurations:

{
  "apiPort": 4001,
  "uiPort": 4000,
  "startUI": true,
  "webhookUrl": "http://localhost:3000/webhook/sms",
  "cors": {
    "enabled": true,
    "origins": ["*"]
  },
  "logging": {
    "enabled": true,
    "level": "info"
  },
  "verbose": false
}

Generate Configuration

Use the init command to generate a sample configuration:

sms-dev init

Creates sms-dev.config.js

sms-dev init --json

Creates sms-dev.config.json

Environment Variables

Environment variables provide system-level configuration and are useful for deployment environments.

Available Variables

VariableTypeDescription
SMS_DEV_API_PORTnumberAPI server port
SMS_DEV_UI_PORTnumberUI server port
SMS_DEV_WEBHOOK_URLstringWebhook URL
SMS_DEV_NO_UIbooleanDisable UI server
SMS_DEV_VERBOSEbooleanEnable verbose logging

Usage Examples

Set environment variables:

export SMS_DEV_API_PORT=5001
export SMS_DEV_UI_PORT=5000
export SMS_DEV_WEBHOOK_URL=http://localhost:3000/webhook
sms-dev start

Inline environment variables:

SMS_DEV_VERBOSE=true sms-dev start --no-ui

Configuration Options Reference

Server Options

apiPortnumberdefault: 4001

Port for the API server that handles SMS message requests.

uiPortnumberdefault: 4000

Port for the Virtual Phone UI web interface.

startUIbooleandefault: true

Whether to start the Virtual Phone UI server alongside the API server.

Webhook Options

webhookUrlstringoptional

URL to forward inbound SMS messages to your application for webhook testing.

Logging Options

verbosebooleandefault: false

Enable verbose logging for debugging and development.

logging.enabledbooleandefault: true

Whether to enable logging output.

logging.levelstringdefault: "info"

Logging level: "debug", "info", "warn", or "error".

Debugging Configuration

Use these commands to debug configuration issues:

Show Current Configuration

sms-dev config

Displays the resolved configuration from all sources

Show Configuration and Exit

sms-dev start --show-config

Shows what configuration would be used without starting servers

Use Specific Config File

sms-dev start --config /path/to/custom.config.js

Load configuration from a specific file path

Next Steps

CLI Reference

Learn about all available CLI commands and their options.

View CLI Reference →

API Reference

Explore the API endpoints for integrating with sms-dev.

API Documentation →