Getting Started
This guide will help you get started with BeamCLI for secure terminal sharing.
Option 1: Web Client (No Installation)
The fastest way to join a terminal sharing session.
Joining a Session
- Open beamcli.com/app in your browser
- Enter the 5-character session code
- Click “Join”
- Watch the shared terminal in real-time
Direct Link
You can also join directly with a URL:
https://beamcli.com/app?code=XXXXX
Option 2: VS Code Extension
Share your terminal directly from VS Code, Cursor, or Antigravity.
Installation
- Open VS Code
- Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
- Search for “BeamCLI”
- Click Install
Marketplace listing is in progress. Use the VSIX install method in the VS Code Extension guide if needed.
Sharing Your Terminal
- Open the BeamCLI Terminal panel (View → BeamCLI Terminal)
- Use the terminal normally
- Click the “BeamCLI” button when ready to share
- Sign in to your account
- Choose permission level:
- Read-only (recommended): Viewers can only watch
- Interactive: Viewers can type commands
- Share the displayed session code
Features
- Works as a normal terminal without network
- Local-first: No data sent until you click “BeamCLI”
- Session codes auto-expire for security
Option 3: Command Line Interface
Install the CLI for terminal-based sharing.
Installation
From npm (when published):
npm install -g @beam/cli
From source:
git clone https://github.com/wu-hongjun/beam-cli.git
cd beam-cli
npm install --legacy-peer-deps
npm run build:all
# Run CLI
./dist/apps/beam-cli/bin/run share
./dist/apps/beam-cli/bin/run connect <code>
Hosting a Session
# Start sharing (read-only)
beam share
# Start with interactive mode
beam share --permission write
# Start with Ultra Safe Mode (requires passkey)
beam share --ultra-safe
Joining a Session
beam connect XXXXX
Replace XXXXX with the session code.
Account & Authentication
Creating an Account
- Visit accounts.riverps.com
- Sign up with email or OAuth provider
- Verify your email
Login Methods
- Email/Password: Traditional authentication
- Google OAuth: Sign in with Google
- Passkey/WebAuthn: Use a hardware security key
Session Management
View and manage your active sessions in your account dashboard.
Permission Levels
When sharing, choose the appropriate permission level:
| Permission | Description | Use Case |
|---|---|---|
| Read-only | Viewers can only watch | Demonstrations, teaching |
| Interactive | Viewers can type commands | Pair programming, collaboration |
Security Note: Only enable interactive mode with trusted collaborators.
Ultra Safe Mode
For maximum security, use Ultra Safe Mode with a hardware security key.
Requirements
- Physical security key (YubiKey, etc.)
- Key must support WebAuthn PRF extension
How It Works
- Host starts session with
--ultra-safeflag - Host authenticates with their passkey
- Viewers must authenticate with the same physical key
- Encryption uses PRF-derived secret + ECDH
Benefits
- Same passkey required for host AND viewers
- Even with the session code, attackers cannot decrypt without the key
- Zero-knowledge: Server cannot decrypt data
Troubleshooting
Cannot Connect to Session
- Verify the session code is correct (case-insensitive)
- Check if the session has expired
- Ensure you have network connectivity
Terminal Not Displaying
- Refresh the page
- Check browser console for errors
- Try a different browser (Chrome, Firefox, Safari)
VS Code Extension Issues
- Ensure the extension is up to date
- Restart VS Code
- Check the Output panel for errors
Next Steps
- CLI Reference - Full command documentation
- Security Guide - How encryption protects your data
- FAQ - Common questions and answers