CLI Authentication

Authentication Methods

The Rexec CLI supports two authentication methods:

Browser-based OAuth - Interactive login with browser
API Token - Direct authentication with token

The recommended method for interactive users.

rexec login

The CLI will:

Start a local callback server on port 9876
Open your default browser
Redirect to Rexec login page
Wait for authentication

Step 2: Complete in Browser

╔══════════════════════════════════════════╗
║           Rexec CLI Login                ║
╚══════════════════════════════════════════╝

Opening browser for login...

If browser doesn't open, visit:
https://rexec.pipeops.io/cli-login?callback=http://localhost:9876/callback

Waiting for login... (Press Ctrl+C to cancel)

In the browser:

Login or signup to Rexec
Authorize CLI access
Browser shows “Login Successful!”
Return to terminal

Step 3: Verify Success

✓ Successfully logged in as johndoe ([email protected])

You can now use rexec commands or run rexec -i for interactive mode.

Timeout and Errors

The login flow times out after 5 minutes. If you encounter issues:

Login timed out. Please try again.

Or if the callback server can’t start:

Couldn't start local server: address already in use

Manual login:
1. Go to: https://rexec.pipeops.io/settings
2. Click on 'API Tokens' section
3. Generate a new token and copy it

Paste your token here: [enter token]

API Token Authentication

Generate an API Token

Login to Rexec Dashboard
Navigate to Settings → API Tokens
Click Generate New Token
Copy the token (starts with rexec_)

API tokens are shown only once. Store them securely!

rexec login --token rexec_abc123def456ghi789xyz

The CLI validates the token and stores your credentials:

✓ Logged in as johndoe ([email protected])

Token Types

Rexec supports two token types:

Generated during OAuth flow
Short-lived (configurable expiration)
Stored in ~/.rexec/config.json
Format: Standard JWT (3 base64 segments)

API Tokens

Generated in dashboard settings
Long-lived (no expiration by default)
Prefixed with rexec_
Validated via /api/tokens/validate endpoint

Configuration Storage

Authentication data is stored in ~/.rexec/config.json:

{
  "host": "https://rexec.pipeops.io",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "johndoe",
  "email": "[email protected]",
  "tier": "pro"
}

File Permissions

The config file has restricted permissions for security:

# Automatically set by CLI
-rw------- 1 user user 245 Mar 4 10:00 /home/user/.rexec/config.json

File permissions are 0600 (owner read/write only) to protect your credentials.

Environment Variables

Override config file values with environment variables:

# Set custom host
export REXEC_HOST="https://custom.rexec.io"

# Set token directly (bypasses config file)
export REXEC_TOKEN="rexec_your_token_here"

# Use CLI
rexec whoami

Precedence:

Environment variables (highest)
Config file
Default values (lowest)

Check Authentication Status

Verify you’re logged in:

rexec whoami

Output:

User Profile
─────────────────────────────
  Username: johndoe
  Email:    [email protected]
  Tier:     pro
  Role:     Admin
  Host:     https://rexec.pipeops.io

If Not Authenticated:

Not logged in. Run 'rexec login' first.

Logout

Clear stored credentials:

rexec logout

This removes ~/.rexec/config.json completely.

✓ Logged out

Re-authentication

If your token expires or becomes invalid:

$ rexec ls
Error: Invalid token: unauthorized

# Login again
$ rexec login

Multiple Accounts

To switch between accounts:

# Logout from current account
rexec logout

# Login with different account
rexec login

Security Best Practices

Protect Your Token

Do:

Store tokens securely
Use environment variables in CI/CD
Rotate tokens periodically
Use short-lived tokens in production

Don’t:

Commit tokens to version control
Share tokens via insecure channels
Use the same token across multiple machines
Store tokens in plain text scripts

CI/CD Authentication

For automated pipelines, use API tokens via environment variables:

# GitHub Actions example
- name: Deploy with Rexec
  env:
    REXEC_TOKEN: ${{ secrets.REXEC_TOKEN }}
  run: |
    rexec create --name ci-build
    rexec run deploy-script --terminal ci-build

Shared Machines

On shared systems:

# Use temporary token for session
export REXEC_TOKEN="rexec_temp_token"
rexec ls

# Unset when done
unset REXEC_TOKEN

This prevents storing credentials in shared config files.

Troubleshooting

Port 9876 Already in Use

If the callback server can’t start:

Couldn't start local server: listen tcp :9876: bind: address already in use

Solutions:

Stop any service using port 9876
Use manual token login: rexec login --token YOUR_TOKEN

Browser Doesn’t Open

If the browser doesn’t auto-open:

Copy the URL from the terminal

Manually open in browser:

https://rexec.pipeops.io/cli-login?callback=http://localhost:9876/callback

Invalid Token Error

Invalid token: token signature is invalid

Causes:

Token expired
Token revoked in dashboard
Wrong API host

Solution:

rexec logout
rexec login

Configuration File Corrupted

If config file is corrupted:

rm ~/.rexec/config.json
rexec login

API Endpoints

The CLI uses these authentication endpoints:

Endpoint	Method	Purpose
`/cli-login`	GET	Browser OAuth flow
`/api/profile`	GET	Get user profile (JWT)
`/api/tokens/validate`	GET	Validate API token

Token Format

JWT Token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwiZXhwIjoxNjgwMDAwMDAwfQ.signature

Parts:

Header (algorithm + type)
Payload (user data + expiration)
Signature (verification)

API Token

rexec_1234567890abcdefghijklmnopqrstuvwxyz

Format:

Prefix: rexec_
Length: 40-64 characters
Characters: alphanumeric

Next Steps

CLI Commands

Explore all available CLI commands

TUI Dashboard

Launch interactive terminal UI

Command Line

TUI

CLI Authentication

Authentication Methods

Step 2: Complete in Browser

Step 3: Verify Success

Timeout and Errors

API Token Authentication

Generate an API Token

Token Types

API Tokens

Configuration Storage

File Permissions

Environment Variables

Check Authentication Status

Logout

Re-authentication

Multiple Accounts

Security Best Practices

Troubleshooting

Port 9876 Already in Use

Browser Doesn’t Open

Invalid Token Error

Configuration File Corrupted

API Endpoints

Token Format

JWT Token

API Token

Next Steps

CLI Commands

TUI Dashboard

Build docs developers (and LLMs) love

Command Line

TUI

​Authentication Methods

​Browser-Based Login

​Step 1: Start Login Flow

​Step 2: Complete in Browser

​Step 3: Verify Success

​Timeout and Errors

​API Token Authentication

​Generate an API Token

​Login with Token

​Token Types

​JWT Tokens (Browser Login)

​API Tokens

​Configuration Storage

​File Permissions

​Environment Variables

​Check Authentication Status

​Logout

​Re-authentication

​Multiple Accounts

​Security Best Practices

​Troubleshooting

​Port 9876 Already in Use

​Browser Doesn’t Open

​Invalid Token Error

​Configuration File Corrupted

​API Endpoints

​Token Format

​JWT Token

​API Token

​Next Steps

CLI Commands

TUI Dashboard

Build docs developers (and LLMs) love

Authentication Methods

Browser-Based Login

Step 1: Start Login Flow

Step 2: Complete in Browser

Step 3: Verify Success

Timeout and Errors

API Token Authentication

Generate an API Token

Login with Token

Token Types

JWT Tokens (Browser Login)

API Tokens

Configuration Storage

File Permissions

Environment Variables

Check Authentication Status

Logout

Re-authentication

Multiple Accounts

Security Best Practices

Troubleshooting

Port 9876 Already in Use

Browser Doesn’t Open

Invalid Token Error

Configuration File Corrupted

API Endpoints

Token Format

JWT Token

API Token

Next Steps