CLI Reference

Complete command reference for the BeamCLI command-line tool.

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

# The CLI is now available at:
./dist/apps/beam-cli/bin/run <command>

Commands

beam share

Start a terminal sharing session.

beam share [options]

Options

Option	Alias	Description	Default
--permission	-p	Permission level: read or write	read
--server	-s	WebSocket server URL	Production server
--ultra-safe		Require passkey authentication	false
--help	-h	Show help

Examples

# Start a read-only session
beam share

# Start an interactive session
beam share --permission write
beam share -p write

# Use a custom server
beam share --server ws://localhost:3000/ws

# Ultra Safe Mode (requires passkey)
beam share --ultra-safe

Output

Starting terminal sharing session...
Authenticating...

Session started!
Share this code with viewers: ABCDE

Viewers can join at: https://beamcli.com/app?code=ABCDE

Press Ctrl+C to end the session

---

beam connect

Connect to an existing sharing session.

beam connect <code> [options]

Arguments

Argument	Description	Required
code	5-character session code	Yes

Options

Option	Alias	Description	Default
--server	-s	WebSocket server URL	Production server
--help	-h	Show help

Examples

# Connect to a session
beam connect ABCDE

# Connect using custom server
beam connect ABCDE --server ws://localhost:3000/ws

Output

Connecting to session ABCDE...
Connected!

You are viewing the shared terminal.
Press Ctrl+C to disconnect.

---

beam help

Display help information.

beam help [command]

Examples

# General help
beam help

# Help for specific command
beam help share
beam help connect

---

Configuration

Environment Variables

Variable	Description	Default
BEAM_SERVER	Default WebSocket server URL	Production server
BEAM_AUTH_TOKEN	Authentication token

Configuration File

BeamCLI can use a configuration file at ~/.beamrc:

{
  "server": "wss://custom-server.com/ws",
  "defaultPermission": "read"
}

---

Authentication

Login

The CLI stores credentials in your system’s secure storage:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (libsecret)

When you first run beam share, you’ll be prompted to log in.

Token-Based Auth

For CI/CD or automation, use environment variables:

export BEAM_AUTH_TOKEN="your-api-token"
beam share

Generate API tokens in your account settings.

---

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Authentication failed
4	Connection failed
5	Session not found

---

Tips

Shell Integration

Add an alias for quick sharing:

# Add to ~/.bashrc or ~/.zshrc
alias share="beam share"
alias join="beam connect"

SSH Sharing

Share your SSH session:

# On your machine
ssh user@server

# Then share
beam share

Screen Recording Alternative

Use BeamCLI instead of screen recording for live terminal demos:

# Start sharing
beam share

# Share the URL with your audience
# Viewers see your terminal in real-time

---

Troubleshooting

“Command not found”

Ensure npm’s global bin is in your PATH:

# Show npm global bin directory
npm bin -g

# Add to PATH (add to shell config for persistence)
export PATH="$PATH:$(npm bin -g)"

“Authentication failed”

1. Check your internet connection
2. Verify your credentials
3. Try logging out and back in:

   beam logout
   beam share  # Will prompt for login
   

“Connection refused”

1. Check the server URL
2. Verify the server is running
3. Check for firewall blocking

---

See Also

• Getting Started
• Security
• FAQ