Documentation
CLI

Command Line Interface

A comprehensive command-line tool for managing your Flux Relay messaging platform from the terminal.

Introduction

╔═══════════════════════════════════════════════════════╗
║                                                       ║
║     ███████╗██╗     ██╗   ██╗██╗  ██╗                ║
║     ██╔════╝██║     ██║   ██║╚██╗██╔╝                ║
║     █████╗  ██║     ██║   ██║ ╚███╔╝                 ║
║     ██╔══╝  ██║     ██║   ██║ ██╔██╗                 ║
║     ██║     ███████╗╚██████╔╝██╔╝ ██╗                ║
║     ╚═╝     ╚══════╝ ╚═════╝ ╚═╝  ╚═╝                ║
║                    ─                                   ║
║     ██████╗ ███████╗██╗     █████╗ ██╗   ██╗         ║
║     ██╔══██╗██╔════╝██║    ██╔══██╗╚██╗ ██╔╝         ║
║     ██████╔╝█████╗  ██║    ███████║ ╚████╔╝          ║
║     ██╔══██╗██╔══╝  ██║    ██╔══██║  ╚██╔╝           ║
║     ██║  ██║███████╗███████╗██║  ██║   ██║            ║
║     ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═╝   ╚═╝            ║
║                                                       ║
║          Command Line Interface v1.0.0                ║
╚═══════════════════════════════════════════════════════╝

Flux Relay CLI is a powerful command-line tool for managing your Flux Relay messaging platform. It provides a comprehensive interface for database operations, nameserver management, and SQL query execution. Built with Go and featuring an interactive SQL shell similar to Turso, the CLI enables developers to efficiently manage their messaging infrastructure from the terminal.

The CLI follows a hierarchical structure: Projects → Servers → Nameservers, allowing you to organize and manage your messaging platform resources with context-aware commands.

Key Features

  • OAuth 2.0 Device Authorization Grant: Secure authentication flow
  • Interactive SQL Shell: Turso-like interface for SQL operations
  • Project Management: List and select projects
  • Server Management: Manage servers within projects
  • Nameserver Management: Create and manage databases
  • Headless Mode: Support for WSL, SSH, and CI/CD environments

Installation

┌─────────────────────────────────────────┐
│  INSTALLATION                            │
│  ═══════════════════════════════════════ │
│                                          │
│  Ready to get started? Let's install!   │
└─────────────────────────────────────────┘

Prerequisites

Before installing Flux Relay CLI, ensure you have:

  • Go 1.21+ (for building from source)
  • Git (for cloning the repository)
  • Internet connection (for authentication and API calls)

Install from Source

bash
git clone https://github.com/postacksol/flux-relay-cli.git
cd flux-relay-cli
go build -o flux-relay .
sudo mv flux-relay /usr/local/bin/

Verify Installation

bash
flux-relay --version

Authentication

┌─────────────────────────────────────────┐
│  AUTHENTICATION                          │
│  ═══════════════════════════════════════ │
│                                          │
│  Secure access to your platform         │
└─────────────────────────────────────────┘

Flux Relay CLI uses OAuth 2.0 Device Authorization Grant flow for secure authentication. This allows you to authenticate without exposing your credentials in the terminal.

Login

To authenticate with Flux Relay, run:

bash
flux-relay login

This will:

  1. Generate a device code and user code
  2. Open your browser automatically to complete authentication
  3. Wait for you to authorize the device
  4. Save your access token securely to ~/.flux-relay/config.json

Manual Token Configuration

If you have an access token, you can set it manually:

bash
flux-relay config set token "YOUR_TOKEN_HERE"

Logout

To log out and remove your stored token:

bash
flux-relay logout

Security Note: Tokens are stored with secure file permissions (0600) in ~/.flux-relay/config.json, ensuring only you can read your credentials.

Upgrading

┌─────────────────────────────────────────┐
│  UPGRADING                               │
│  ═══════════════════════════════════════ │
│                                          │
│  Keep your CLI up to date!              │
└─────────────────────────────────────────┘

To upgrade Flux Relay CLI to the latest version, pull the latest changes from the repository and rebuild:

bash
cd flux-relay-cli
git pull origin main
go build -o flux-relay .
sudo mv flux-relay /usr/local/bin/

After upgrading, verify the new version:

bash
flux-relay --version

Help

┌─────────────────────────────────────────┐
│  HELP                                    │
│  ═══════════════════════════════════════ │
│                                          │
│  Need assistance? We've got you!        │
└─────────────────────────────────────────┘

Get help with any command by using the --help flag:

bash
flux-relay --help

Get help for a specific command:

bash
flux-relay login --help

Headless Mode

┌─────────────────────────────────────────┐
│  HEADLESS MODE                           │
│  ═══════════════════════════════════════ │
│                                          │
│  No browser? No problem!                │
└─────────────────────────────────────────┘

Headless mode is designed for environments where a browser cannot be opened automatically, such as WSL, SSH sessions, or CI/CD pipelines.

Using Headless Mode

Run login with the --headless flag:

bash
flux-relay login --headless

This will:

  1. Display a device code and verification URL
  2. Provide instructions to manually visit the URL
  3. Show how to copy the token after authentication

Note: In headless mode, you'll need to manually copy the access token from the success page and run flux-relay config set token "YOUR_TOKEN" to complete authentication.

Commands

┌─────────────────────────────────────────┐
│  COMMANDS                                │
│  ═══════════════════════════════════════ │
│                                          │
│  Master the CLI with these commands     │
└─────────────────────────────────────────┘

Authentication Commands

flux-relay login
Interactive

Authenticate with Flux Relay using OAuth 2.0 Device Authorization Grant. Opens your browser automatically to complete authentication.

flux-relay login --headless
Headless

Authenticate without opening a browser. Perfect for WSL, SSH sessions, and CI/CD pipelines. You'll receive a device code to enter manually.

flux-relay logout

Log out and remove your stored authentication token from ~/.flux-relay/config.json.

flux-relay config set token <token>

Manually set your access token if you have one. Useful for CI/CD or when copying tokens from other sources.

Project Commands

flux-relay pr list

List all projects in your account

flux-relay pr <name-or-id>

Select a project to work with

Server Commands

flux-relay server list

List all servers in the selected project

flux-relay server <name-or-id>

Select a server

flux-relay server shell <name-or-id>

Open interactive SQL shell for a server

Nameserver Commands

flux-relay ns list

List all nameservers in the selected server

flux-relay ns create <name>

Create a new nameserver

flux-relay ns initialize <name-or-id>

Initialize default messaging platform tables

flux-relay ns shell <name-or-id>

Open interactive SQL shell for a nameserver

SQL Commands

flux-relay sql "SELECT * FROM table"

Execute a one-off SQL query

Configuration Commands

flux-relay config set token <token>

Set access token manually

API Reference