Docs/CLI Reference
SECTION 02Command-Line Tool

CLI Reference

The LMESH CLI connects your local operating system shell (POSIX PTY / ConPTY) to the relay server via secure WebSockets. Below is the complete syntax, flag specifications, and practical usage examples for all subcommands.

Package: lmesh-cli
npm i -g lmesh-cliView on npm

Command Syntax

All LMESH commands can be invoked using either lmesh (when installed globally) or npx lmesh-cli:

syntax
$lmesh <command> [options]
lmesh login

Authenticate CLI identity via GitHub Device Authorization Flow.

lmesh share [options]

Spawn a local pseudo-terminal and stream live over WebSockets.

lmesh whoami

Display active authenticated GitHub profile and credentials status.

lmesh logout

Revoke and clear locally stored credentials from disk.

lmesh login

auth

Initiates GitHub OAuth Device Authorization. The CLI prints a one-time 8-character user code and automatically opens GitHub's verification page. Once authorized, an encrypted JWT is saved to ~/.lmesh/auth.json.

bash
$lmesh login

lmesh share

core

Spawns your operating system's native pseudo-terminal (POSIX PTY on macOS/Linux, ConPTY on Windows) and initiates a real-time WebSocket session. Collaborators join via the generated browser URL.

bash
$lmesh share [options]
Common Usage Scenarios:
1. Default Local Session
$lmesh share

Connects to the default relay server at localhost:3001 and generates a join URL for localhost:3000.

2. Password-Protected Session
$lmesh share --password mySecretPass123

Requires all joining collaborators to enter this passphrase before accessing the terminal output.

3. Read-Only Broadcast Mode
$lmesh share --readonly

Collaborators join strictly as viewers. Remote control requests and keyboard input are disabled.

4. Cloud Relay Connection
$lmesh share --url wss://relay.yourdomain.com

Connects directly to your hosted production relay server and prints the production web URL (https://lmesh.vercel.app/[id]).

lmesh whoami

utility

Inspects your local credentials configuration and outputs the active GitHub username, user ID, and auth status.

bash
$lmesh whoami

lmesh logout

utility

Safely removes the stored JWT token and user profile from ~/.lmesh/auth.json.

bash
$lmesh logout

Command Flags & Options

Summary of all command-line flags accepted by lmesh share:

FlagAliasTypeDefaultDescription
--port-pnumber3001Port of the relay WebSocket server.
--host-hstringlocalhostHostname of the relay WebSocket server.
--url-ustringnoneDirect WebSocket URL override (e.g. wss://relay.example.com).
--password-wstringnonePassphrase required for collaborators to join the session.
--readonly-rbooleanfalseStart session in read-only broadcast mode (no control requests).
--help-hbooleanfalsePrint usage guide and options list to stdout.
--version-VbooleanfalseDisplay the installed CLI version number.
Previous: Quick StartNext: Controls & Hotkeys