@lumerahq/cli

CLI for building and deploying Lumera apps.

Installation

npm install -g @lumerahq/cli
# or use directly with npx/pnpm dlx
pnpm dlx @lumerahq/cli init my-app

Commands

lumera init [name]         # Scaffold a new Lumera app
lumera login               # Authenticate with Lumera
lumera logout              # Clear stored credentials
lumera whoami              # Show current user
lumera status              # Show project info

lumera dev                 # Start dev server
lumera apply app           # Deploy frontend
lumera destroy app         # Delete app from Lumera

lumera plan                # Preview changes (with inline diffs)
lumera diff <resource>     # Full diff between local and remote
lumera apply               # Apply collections, automations, hooks, agents
lumera pull                # Pull remote state to local
lumera list                # List resources with sync status
lumera show <resource>     # Show resource details
lumera destroy             # Delete remote resources

lumera run <target>        # Run script, automation, or invoke agent

lumera flags list          # List this sandbox's feature flags
lumera flags get <key>     # Print one flag's value (--default <v> if unset)

Scaffolding Projects

Interactive Mode

lumera init                # Prompts for project name and directory
lumera init my-app         # Prompts for directory only

Non-Interactive Mode

For CI/CD or scripted environments, use -y (or --yes) flag:

lumera init my-app -y                 # Creates ./my-app
lumera init my-app -y --dir ./apps    # Creates ./apps
lumera init my-app -y --force         # Overwrites if directory exists
lumera init my-app -y --no-install    # Skip pnpm install

Init Options

| Flag | Short | Description | |------|-------|-------------| | --template <name> | -t | Template to use (currently bundled: default) | | --yes | -y | Non-interactive mode (project name required) | | --dir <path> | -d | Target directory (defaults to project name) | | --force | -f | Overwrite existing directory without prompting | | --no-install | | Skip dependency installation | | --open | -o | Open project in editor after scaffolding | | --help | -h | Show help |

CI/CD Example

# Full non-interactive setup
lumera init my-app -y -f

Authentication

Interactive Login

lumera login

Opens a browser for OAuth authentication. Credentials are stored locally.

CI/CD Usage

For automated environments, use the LUMERA_TOKEN environment variable:

export LUMERA_TOKEN=your_api_token
lumera apply app

The CLI checks for credentials in this order:

1. LUMERA_TOKEN environment variable
2. Project-local credentials (.lumera/credentials.json)
3. Global credentials (~/.config/lumera/credentials.json)

Automation schedules in config.json

Automations can define schedules in two supported shapes.

Canonical format

{
  "external_id": "my-app:daily-report",
  "name": "Daily Report",
  "inputs": {
    "schema": {
      "function": {
        "name": "main",
        "parameters": { "type": "object" }
      }
    },
    "presets": {
      "daily": {
        "label": "Daily Run",
        "inputs": { "region": "west" }
      }
    }
  },
  "schedule": {
    "cron": "0 7 * * *",
    "timezone": "America/Los_Angeles",
    "preset": "daily"
  }
}

Shorthand format

{
  "external_id": "my-app:daily-report",
  "name": "Daily Report",
  "inputs": {
    "schema": {
      "function": {
        "name": "main",
        "parameters": { "type": "object" }
      }
    }
  },
  "schedule": "0 7 * * *",
  "schedule_tz": "America/Los_Angeles",
  "schedule_inputs": { "region": "west" }
}

Notes:

• schedule_inputs creates/updates a schedule preset automatically.
• If you already define inputs.presets, you can point the schedule at one with schedule_preset (or schedule.preset).
• If exactly one preset exists, the CLI uses it automatically.

Security

Credential Storage

• Never commit credentials: The .lumera/ directory is gitignored by default in scaffolded projects
• Token scope: Use tokens with minimal required permissions for CI/CD
• Rotation: Rotate tokens periodically, especially after team member offboarding

Environment Variables

• LUMERA_TOKEN - API token for authentication (recommended for CI/CD)
• LUMERA_BASE_URL - Override base URL (defaults to https://app.lumerahq.com)
• LUMERA_API_URL - Override API URL (defaults to https://app.lumerahq.com/api)

Best Practices

1. Use lumera login for local development (stores credentials securely)
2. Use LUMERA_TOKEN for CI/CD pipelines
3. Never hardcode tokens in scripts or config files
4. Keep .lumera/ in .gitignore to prevent accidental credential commits

License

MIT