CLI Reference

Command-line interface for RelayPlane workflow management and cloud integration.

Installation

The CLI is included with the SDK, or install it separately:

1# Install with SDK (recommended)
2npm install @relayplane/sdk
3
4# Or install CLI only
5npm install -g @relayplane/proxy

The CLI provides two commands: relay and relayplane (both are aliases).

Commands

relay login

Authenticate with RelayPlane Cloud using device OAuth flow. Opens a browser for secure authentication.

1npx relay login
2
3# Output:
4# RelayPlane CLI - Login
5#
6# 🔐 Starting device authorization...
7#
8# ┌─────────────────────────────────────────────────────────┐
9# │ Please complete the following steps to login:           │
10# │                                                          │
11# │ 1) Open this URL in your browser:                       │
12# │    https://relayplane.com/auth/device                   │
13# │                                                          │
14# │ 2) Enter this code:                                      │
15# │    ABCD-1234                                             │
16# │                                                          │
17# │ Waiting for you to complete login...                    │
18# └─────────────────────────────────────────────────────────┘

relay logout

Clear cloud credentials and disconnect from RelayPlane Cloud.

1npx relay logout

relay status

Show current CLI status, cloud connection, and detected workflows.

1npx relay status
2
3# Output (when connected):
4# RelayPlane Status
5# ─────────────────
6# Mode: Local + Cloud
7# Team: my-team
8# Plan: pro
9#
10# Cloud features:
11#   ✓ Webhooks
12#   ✓ Scheduled workflows
13#   ✓ Run history
14#   ✓ Cloud telemetry
15#   ✓ Team access
16#
17# Project:
18#   Workflows: 5 detected
19
20# Output (local only):
21# RelayPlane Status
22# ─────────────────
23# Mode: Local-only
24# Cloud: Not connected
25# Workflows: 3 local workflows detected

relay workflows

List all workflows discovered in the current project.

1npx relay workflows
2
3# Output:
4# Discovering workflows in current project...
5#
6# Found 3 workflows:
7#
8# ────────────────────────────────────────────────────────────────────────────────
9# Name                          Steps     Cloud          File
10# ────────────────────────────────────────────────────────────────────────────────
11# invoice-processor             3         ✓ enabled      invoice.ts
12# ticket-router                 2         ✓ enabled      support.ts
13# greeting-workflow             2         -              greet.ts
14# ────────────────────────────────────────────────────────────────────────────────
Workflows are discovered from common locations: workflows/, src/workflows/, and app/workflows/

relay sync

Sync local workflows with RelayPlane Cloud. Registers workflows for webhooks, schedules, and tracking.

1npx relay sync
2
3# Output:
4# Discovering workflows...
5# Found 3 workflows
6#
7# Syncing with RelayPlane Cloud...
8#
9# ✓ invoice-processor              synced
10# ↻ ticket-router                  updated
11# - greeting-workflow              unchanged
12#
13# ✓ 2 workflows synced successfully.
14#
15# Your workflows are now available for:
16#   • Webhook triggers
17#   • Scheduled execution
18#   • Run history tracking
19#   • Team collaboration

relay dashboard

Open the RelayPlane Cloud dashboard in your browser.

1npx relay dashboard

relay watch

Live cost ticker. Polls the local proxy and renders today's spend, the active session, model distribution, and the last 5 requests. The screen redraws in place, so it reads like a dashboard, not a scrolling log. Ctrl-C to exit.

1# Defaults: polls http://localhost:4100 every 3000ms
2npx relay watch
3
4# Point at a different proxy or change the poll interval
5npx relay watch --proxy http://localhost:4101 --interval 1000
6
7# Sample output:
8# RelayPlane Watch (live cost ticker)
9# ───────────────────────────────────
10# Today's spend: $1.2340
11# Current session: $0.4210
12#
13# Model distribution:
14#   claude-sonnet-4-6: 14 requests
15#   claude-opus-4-7: 3 requests
16#
17# Recent requests (last 5):
18#   claude-sonnet-4-6  $0.0411  2844ms
19#   claude-opus-4-7    $0.1748  19062ms

The ticker reads from the proxy's /v1/stats/live endpoint, so it works in fully local mode, no cloud login required.

Workflow Discovery

The CLI automatically discovers workflows in these locations:

  • •workflows/
  • •src/workflows/
  • •app/workflows/

Place your workflow files in any of these directories and they'll be automatically detected.

Cloud Features

When connected to RelayPlane Cloud, your workflows gain access to:

  • •Webhooks - Trigger workflows via HTTP requests
  • •Schedules - Run workflows on cron schedules
  • •Run History - View past executions and outputs
  • •Team Access - Collaborate with team members
  • •Telemetry - Monitor performance and costs

Typical Workflow

1# 1. Login to cloud (one-time)
2npx relay login
3
4# 2. Check status
5npx relay status
6
7# 3. List discovered workflows
8npx relay workflows
9
10# 4. Sync workflows to cloud
11npx relay sync
12
13# 5. Open dashboard to configure webhooks/schedules
14npx relay dashboard

Local-Only Mode

RelayPlane works completely offline without cloud connection. Cloud features are optional additions for:

  • •Teams that need webhook triggers
  • •Scheduled/recurring workflows
  • •Historical run tracking
  • •Team collaboration
Local-first means your workflows run on your infrastructure using your API keys. There's no gateway tax or data passing through our servers.

Troubleshooting

No workflows found

Ensure your workflow files are in one of the discovery locations and export workflows properly:

1// src/workflows/my-workflow.ts
2import { relay } from '@relayplane/sdk';
3
4export const myWorkflow = relay
5  .workflow('my-workflow')
6  .step('process')
7  .with('openai:gpt-4o')
8  .prompt('Process the input...');

Login issues

If login fails or times out:

  • 1.Ensure you have internet connectivity
  • 2.Try relay logout then relay login again
  • 3.Check if your browser blocked the popup