Relesio CLI

Command-line tool for Relesio — 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

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

From source (monorepo)

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

Link locally:

cd apps/cli
bun link

Quick Start

1. Authenticate via browser (recommended):

   relesio auth login

   Press Enter and your browser opens the Relesio sign-in and consent page. The CLI waits on 127.0.0.1 for the browser to come back, for up to 5 minutes.

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

   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:

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

3. Deploy to an environment:

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

Commands

Authentication

| Command | Description | | --------------------- | ----------------------------------------------------- | | relesio auth login | Sign in to Relesio in the browser, or with an API key | | 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 versions yank <project> <ver> | Yank a version: ranges and latest's fallback skip it within ~20 s; its exact and id URLs still serve (ADMIN/OWNER) | | relesio versions unyank <project> <ver> | Undo a yank: ranges and latest's fallback include it again (ADMIN/OWNER) | | 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

# Browser sign-in (recommended): Enter opens the browser, the CLI waits on 127.0.0.1 for up to 5 minutes
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

Browser sign-in:

1. Run relesio auth login and press Enter: your browser opens the Relesio sign-in and consent page. Without a terminal the CLI only prints the URL.
2. Sign in and approve. The browser comes back to the CLI on 127.0.0.1. The sign-in must finish within 5 minutes.
3. The CLI stores the sign-in in the OS keychain, or, where no keychain is available, in credentials.json in its config directory: mode 0600 on macOS and Linux, and the directory's NTFS permissions on Windows. On Windows and Linux, once a session without the keychain (over SSH) stores the sign-in in credentials.json, every session uses that file until a relesio auth logout from a session that reaches the keychain.
4. All subsequent commands use the stored sign-in. It lasts 90 days; then run relesio auth login again.

With --no-browser, over SSH, or when the CLI cannot listen on 127.0.0.1, the page shows a CODE#STATE line instead: paste it into the terminal and press Enter.

relesio auth logout ends the sign-in on the server too.

Upload

# 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

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

# Deploy a version by its id (e.g. an id-only upload)
relesio deploy my-app <version-id> --env staging

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

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

Rollback

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

Configuration

Environment Variables

| Variable | Description | Default | | ------------------- | -------------------------------------------------------------------- | ------------------------- | | RELESIO_API_TOKEN | API key (rls_*). Bypasses the stored sign-in — 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 — --version, else version in package.json, else the git tag on HEAD. Each is trimmed and one leading v is stripped (v1.2.3 → 1.2.3), then checked against SemVer 2.0.0 (prerelease and +build kept). An invalid --version is an error (exit 65, nothing uploaded); an invalid package.json or tag value is skipped with a warning. With no valid source the upload is id-only: it has no semver, and you deploy it by its version id (relesio deploy my-app <id>).

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

relesio upload ./dist
relesio deploy --env staging

File Structure

apps/cli/
├── src/
│   ├── index.ts        # CLI root
│   ├── commands/       # Command implementations
│   └── lib/            # API client, config, utilities
└── dist/               # Compiled output; dist/index.js is the bin

Development

# 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

One code per failure class, also listed by relesio --help:

| Code | Meaning | | ---- | ---------------------------------------------------------------------------------------------------------- | | 0 | success | | 64 | usage: an unknown option or command, a missing argument, a prompt with no terminal | | 65 | invalid input: a malformed slug or semver, an ambiguous semver, a dirty tree | | 66 | not found: an API 404, a named project, version, environment, organization or directory; nothing to act on | | 69 | server error: a 5xx a retry will not fix | | 75 | transient, retry: no answer, a timeout, a broken body, 408, 429 or a 5xx | | 77 | not signed in or not allowed: no key, 401, 403, a denied or expired login | | 78 | configuration: no organization context, an unreadable config | | 1 | any other failure, an API error not listed above included |

Links

• Relesio
• Issues

License

MIT