npm package: @relay-works/cli
Description: The official command-line interface for the Relay SMS platform, featuring integrated SMS development tools.
Latest version: 0.0.2

# Relay CLI

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

## Installation

```bash
npm install -g @relay-works/cli
```

## Quick Start

```bash
# 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

```bash
# 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:

```bash
relay config init
```

Example `relay.json`:

```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:

```bash
# 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](https://relay.works)
- [SMS-Dev Tool](https://smsdev.app)
- [Documentation](https://docs.relay.works)

## Support

- GitHub Issues: [relay-works/relay-cli](https://github.com/relay-works/relay-cli)
- Documentation: [docs.relay.works](https://docs.relay.works)
- Support: [support@relay.works](mailto:support@relay.works)

## Local Development (Contributing)

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

1.  **Build the package**:
    ```bash
    npm run build
    ```

2.  **Link globally**:
    ```bash
    npm link
    ```

3.  **Run**:
    You can now use `relay` command anywhere on your system, pointing to your local source.
    ```bash
    relay --version
    ```