CLI
Documentation

Lux Documentation

Welcome to the Lux documentation! The Lux CLI is a command-line interface for managing your Lux workflows, interfaces, and resources directly from your terminal.

Installation

npm install -g lux-cli

Authentication

First, authenticate with your Lux account:

lux login

This command will:

  1. Open your default browser
  2. Redirect you to the Lux authentication page
  3. After successful login, save credentials locally to ~/.lux/config.json
  4. Display your organization ID

Example Output:

Opening browser for authentication...
✓ Successfully authenticated!

Org ID: org_2mgfH7Xk4...

You can now use Lux CLI commands.

Configuration File

Your credentials are stored in ~/.lux/config.json:

{
  "apiKey": "lux_org_2mgfH7Xk4...",
  "orgId": "org_2mgfH7Xk4...",
  "apiUrl": "https://yourdomain.com"
}

Environment Variables

You can override configuration values with environment variables:

  • LUX_API_URL - API endpoint URL
  • LUX_API_KEY - Your API key/token
  • LUX_ORG_ID - Your organization ID

Workflow Management

The Lux CLI provides powerful commands for managing your automation workflows.

Workflow Storage

Workflows are stored in two places:

  • Metadata (name, status, timestamps) → Turso database
  • Configuration (JSON with steps, actions) → R2 storage

Each workflow has two versions:

  • Draft - Work-in-progress changes
  • Published - Live production version

List All Workflows

lux workflows list

Shows all workflows with their ID, name, status, and last updated time.

Example Output:

Found 15 workflow(s):

┌─────┬──────────────────────────┬─────────────┬───────────┐
│ id  │ name                     │ status      │ updated   │
├─────┼──────────────────────────┼─────────────┼───────────┤
│ ... │ 'kevinTest'              │ 'published' │ 10/22/... │
│ ... │ 'Lux movers'             │ 'published' │ 10/22/... │
└─────┴──────────────────────────┴─────────────┴───────────┘

Get Workflow Details

lux workflows get <workflow-id>

Fetches the complete workflow configuration including:

  • Metadata (name, description, status)
  • Draft configuration JSON
  • Published configuration JSON

Example:

lux workflows get 1f8365eb-38ac-4723-8664-15086d6fda91

Create New Workflow

lux workflows create <name> [description]

Creates a new workflow with the given name and optional description.

Example:

lux workflows create "My New Workflow" "Handles customer inquiries"

Save Configuration

lux workflows save <workflow-id> <config-file>

Saves a workflow configuration as a draft. This:

  1. Uploads the JSON config to R2 storage
  2. Updates the database with the new draft URL and hash
  3. Does NOT affect the published version

Example:

lux workflows save 1f8365eb-38ac-4723-8664-15086d6fda91 ./config.json

Publish Workflow

lux workflows publish <workflow-id>

Promotes the draft configuration to production. This:

  1. Copies the draft config to published config in R2
  2. Updates the database with the new published URL and hash
  3. Makes the workflow live

Example:

lux workflows publish 1f8365eb-38ac-4723-8664-15086d6fda91

View Differences

lux workflows diff <workflow-id>

Shows the difference between draft and published configurations.

Workflow Configuration Format

Workflow configs are JSON files with the following structure:

{
  "name": "My Workflow",
  "description": "Workflow description",
  "steps": [
    {
      "id": "step1",
      "type": "action",
      "action": "send_email",
      "config": {
        "to": "user@example.com",
        "subject": "Hello",
        "body": "Message content"
      }
    }
  ],
  "triggers": {
    "type": "api",
    "endpoint": "/webhook"
  }
}

Editing a Workflow

  1. Get the current configuration:
lux workflows get <workflow-id> > workflow.json
  1. Edit the JSON file:
code workflow.json  # or nano workflow.json
  1. Save as draft:
lux workflows save <workflow-id> ./workflow.json
  1. Review changes:
lux workflows diff <workflow-id>
  1. Publish when ready:
lux workflows publish <workflow-id>

Database

Manage and query your Turso database directly from the CLI.

List Tables

lux db tables

View all tables in your organization's database.

Execute SQL

lux sql "<query>"

Run SQL queries against your database.

Example:

lux sql "SELECT * FROM flows LIMIT 10"

Interfaces

Deploy and manage React-based interfaces.

Deploy Interface

lux interfaces deploy <path>

Deploy an interface from a local directory.

Storage

Manage files in R2 storage.

Upload File

lux storage upload <file> <key>

Upload a file to R2 storage.

Secrets

Manage organization secrets securely.

List Secrets

lux secrets list

View all secrets in your organization.

Get Secret

lux secrets get <key>

Retrieve a specific secret value.

Set Secret

lux secrets set <key> <value>

Set or update a secret.

Delete Secret

lux secrets delete <key>

Remove a secret from your organization.

Security:

  • Secrets are stored encrypted
  • Never logged or displayed in plain text
  • Scoped to your organization

Tips & Best Practices

  • Always use lux workflows diff before publishing to production
  • Keep config files in version control (git)
  • Test draft configs before publishing
  • Use descriptive names for workflows
  • Never commit your ~/.lux/config.json to version control
Lux DocumentationREST API