npm package: @lumerahq/cli
Description: CLI for building and deploying Lumera apps
Latest version: 0.18.10

# @lumerahq/cli

CLI for building and deploying Lumera apps.

## Installation

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

## Commands

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

## Scaffolding Projects

### Interactive Mode

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

```bash
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 --install       # Also runs pnpm install
```

### Init Options

| Flag | Short | Description |
|------|-------|-------------|
| `--yes` | `-y` | Non-interactive mode (project name required) |
| `--dir <path>` | `-d` | Target directory (defaults to project name) |
| `--force` | `-f` | Overwrite existing directory without prompting |
| `--install` | `-i` | Install dependencies after scaffolding |
| `--help` | `-h` | Show help |

### CI/CD Example

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

## Authentication

### Interactive Login

```bash
lumera login
```

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

### CI/CD Usage

For automated environments, use the `LUMERA_TOKEN` environment variable:

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

```json
{
  "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

```json
{
  "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