npm package: @relesio/cli
Description: CLI tool for Relesio - Modern Micro-Frontend Hosting
Latest version: 0.3.0

# Relesio CLI

Command-line tool for [Relesio](https://relesio.com) — modern micro-frontend hosting. Upload versions, deploy to environments, and manage projects from the terminal.

## Requirements

- **Node.js** >= 18
- **Bun** (recommended) or **npm** / **pnpm**

## Installation

### From npm

```bash
npm install -g @relesio/cli
# or
bun add -g @relesio/cli
```

### From source (monorepo)

```bash
cd api
bun install
bun run build --filter=@relesio/cli
```

Link locally:

```bash
cd apps/cli
bun link
```

## Quick Start

1. **Authenticate** via browser (recommended):

   ```bash
   relesio auth login
   ```

   The CLI prints a short code, opens your browser to `relesio.com/device`, and waits
   for you to approve. Once approved, a named API key is stored automatically.

   For headless / CI environments, pass an API key directly:

   ```bash
   relesio auth login --token rls_your_token_here
   # or set the environment variable
   export RELESIO_API_TOKEN=rls_your_token_here
   ```

2. **Upload** a built frontend:

   ```bash
   relesio upload ./dist --project my-app --version 1.0.0
   ```

3. **Deploy** to an environment:

   ```bash
   relesio deploy my-app 1.0.0 --env production --yes
   ```

## Commands

### Authentication

| Command               | Description                                      |
| --------------------- | ------------------------------------------------ |
| `relesio auth login`  | Authenticate via browser (device flow) or token  |
| `relesio auth status` | Show current auth state                          |
| `relesio auth logout` | Clear stored credentials                         |
| `relesio whoami`      | Show current user info                           |

### Organizations & Projects

| Command                              | Description                          |
| ------------------------------------ | ------------------------------------ |
| `relesio organizations list`         | List organizations                    |
| `relesio organizations set <org-id>` | Set active organization              |
| `relesio projects list`              | List projects in active organization |
| `relesio team list`                  | List teams                           |
| `relesio team get <teamId>`          | Get team details                     |

### Versions & Deployment

| Command                          | Description                                  |
| -------------------------------- | -------------------------------------------- |
| `relesio versions list <project>`| List versions for a project                  |
| `relesio status <project>`       | Show deployment status across environments   |
| `relesio upload [dir]`           | Upload a new version                         |
| `relesio deploy [project] [ver]` | Deploy a version to an environment           |
| `relesio rollback <project>`     | Rollback to the previous version             |

## Usage Examples

### Authentication

```bash
# Browser-based login (recommended — opens relesio.com/device)
relesio auth login

# Headless / CI: pass an API key directly
relesio auth login --token rls_...

# Or export the token as an environment variable
export RELESIO_API_TOKEN=rls_...
relesio auth status
```

**Device flow steps:**

1. Run `relesio auth login` — a short code is printed in the terminal.
2. Your browser opens automatically to `https://relesio.com/device`.
3. Enter the code (or confirm the pre-filled one), then click **Approve**.
4. The CLI detects the approval, creates a named `rls_*` API key
   (`CLI - <hostname> - <date>`), and stores it locally.
5. All subsequent commands use the stored key automatically.

If the browser cannot open (headless server), the URL and code are printed —
navigate to the URL manually and enter the code. The CLI keeps polling until
you approve, deny, or the 30-minute code expires.

### Upload

```bash
# Basic upload (default dir: dist, uses package.json for project/version)
relesio upload

# Specify directory, project, and version
relesio upload ./build --project my-app --version 1.2.0

# Require clean git working directory
relesio upload ./dist -p my-app -v 1.0.1 --require-clean

# Non-interactive (skip prompts)
relesio upload ./dist -p my-app -v 1.0.0 -y
```

### Deploy

```bash
# Deploy specific version to production
relesio deploy my-app 1.0.0 --env production --yes

# Deploy latest version
relesio deploy my-app --latest --env staging

# Use project from package.json
relesio deploy --env production
```

### Rollback

```bash
relesio rollback my-app --env production --yes
```

## Configuration

### Environment Variables

| Variable            | Description                                                     | Default                   |
| ------------------- | --------------------------------------------------------------- | ------------------------- |
| `RELESIO_API_TOKEN` | API key (`rls_*`). Bypasses device flow — required for CI/CD.  | —                         |
| `RELESIO_API_URL`   | Override the API base URL                                       | `https://api.relesio.com` |
| `RELESIO_ORG_ID`    | Override active organization ID                                 | —                         |
| `DEBUG`             | Enable verbose debug output                                     | —                         |

### Organization Context

Order of precedence:

1. `--org <org-id>` flag
2. `RELESIO_ORG_ID` environment variable
3. Active organization from session

### Output Options

- `--json` — Output as JSON (machine-readable)
- `--no-color` — Disable colored output

## Project & Version Inference

The CLI infers values from `package.json` when possible:

- **Project slug** — from `name` (slugified: lowercase, hyphens)
- **Version** — from `version` (semver)

Example: `package.json` with `"name": "@myorg/my-app"` and `"version": "1.0.0"` allows:

```bash
relesio upload ./dist
relesio deploy --env staging
```

## File Structure

```
api/apps/cli/
├── bin/relesio.js      # Entry shim
├── src/
│   ├── index.ts        # CLI root
│   ├── commands/       # Command implementations
│   └── lib/            # API client, config, utilities
└── dist/               # Compiled output
```

## Development

```bash
# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Type check
bun run type-check

# Lint & format
bun run lint
bun run format
```

## Exit Codes

| Code | Meaning           |
| ---- | ----------------- |
| 0    | Success           |
| 1    | General error     |

## Links

- [Relesio](https://relesio.io)
- [GitHub](https://github.com/relesio/relesio)
- [Issues](https://github.com/relesio/relesio/issues)

## License

MIT