Lunel CLI

Node.js CLI that connects a local machine to the Lunel mobile app through the Lunel gateway. It runs from the project directory you want to expose and keeps filesystem, terminal, process, port, git, and AI actions scoped to that working tree.

Requirements

• Node.js 18 or newer
• npm
• Lunel mobile app for QR/session pairing

Usage

Run the published package:

npx lunel-cli

The CLI prints a QR code and session details. Scan the QR code with the Lunel app to connect to the current working directory.

Common options:

npx lunel-cli --help
npx lunel-cli --new
npx lunel-cli --debug
npx lunel-cli --extra-ports 3000,8080

Options:

| Option | Description | | --- | --- | | -h, --help | Show CLI help | | -n, --new | Create a fresh session code instead of reusing the saved one | | -d, --debug | Enable verbose CLI and AI backend logs | | --extra-ports | Comma-separated local ports to expose through Lunel |

Configuration

By default, the CLI uses the public Lunel services:

• Gateway: https://gateway.lunel.dev
• Manager: https://manager.lunel.dev

Override them with environment variables when developing against local or custom infrastructure:

LUNEL_PROXY_URL=http://localhost:3001 \
LUNEL_MANAGER_URL=http://localhost:3002 \
npx lunel-cli

Other useful environment variables:

| Variable | Description | | --- | --- | | LUNEL_PROXY_URL | Gateway/proxy URL | | LUNEL_MANAGER_URL | Manager URL | | LUNEL_DEBUG | Set to 1 for debug logging | | LUNEL_DEBUG_AI | Set to 1 for AI backend debug logging | | NO_COLOR | Disable colored terminal output | | FORCE_COLOR | Force colored terminal output |

Session config is saved per project root in the OS-specific Lunel config directory:

• macOS: ~/Library/Application Support/lunel/config.json
• Windows: %APPDATA%\lunel\config.json
• Linux: $XDG_CONFIG_HOME/lunel/config.json or ~/.config/lunel/config.json

Development

Install dependencies:

npm install

Build the CLI:

npm run build

Run from source output:

npm run dev

The package entrypoint is dist/index.js, generated from src/index.ts. npm run build compiles TypeScript and marks the generated entrypoint executable.

Project Layout

src/
  index.ts              CLI entrypoint and local machine bridge
  ai/                   Codex/OpenCode provider integration
  transport/            Session transport protocol
  libsodium-wrappers.d.ts

Publishing

The package is published as lunel-cli. prepublishOnly runs the production build before publishing.

npm publish