Docs

Shellular CLI

Run the host agent on your machine, scan the QR code from the Shellular app, and work against your own terminal, files, ports, and AI tools from anywhere.

Quick start View package

Overview

Shellular CLI is the host agent for Shellular. It connects your dev machine to the Shellular relay so the mobile app can reach your environment securely.

Terminal Full PTY sessions that survive CLI reconnects.
Filesystem Browse, read, write, rename, and delete files inside the allowed root.
Ports and proxying Inspect local ports and proxy HTTP or WebSocket traffic.
System monitor and AI Stream CPU, memory, battery, and route prompts to available AI tools.

Requirements

  • Node.js 18 or newer
  • macOS, Linux, or Windows
  • The Shellular mobile app to scan the pairing QR code

Quick start

Start the CLI directly with npx:

npx shellular

The CLI prints a QR code in your terminal. Scan it with the Shellular app to pair your device and connect.

By default, every unknown client must be approved in the terminal before it can connect.

Background mode

To keep Shellular running in the background:

npx shellular start

In daemon mode, unknown clients are not approved interactively. Use shellular clients to review pending devices and approve them.

Stop the host when you are done:

npx shellular stop
Note

Only one instance of Shellular can run at a time per machine.

Commands

Command Description
shellular Run Shellular in the foreground
shellular start Start the background host and print the QR code
shellular stop Stop the background host
shellular status Show host status, PID, restart count, and logs
shellular logs Stream background host logs
shellular clients Review and approve known client devices

Options

Flag Default Description
--server <url> wss://api.shellular.dev Relay server WebSocket URL
--dir <path> $HOME Root directory exposed to the client
--unknown-clients <policy> requires-approval How unknown clients are handled: always-reject, always-allow, or requires-approval
--install-vs-plugin - Install the VS Code extension and exit

Unknown client approval

--unknown-clients only applies to devices that are not already in the local approvals file.

  • requires-approval is the default. In foreground mode, the CLI asks for approval in the terminal.
  • In daemon mode, requires-approval records the client as pending and rejects the connection until you approve it with shellular clients.
  • always-allow accepts unknown clients immediately and does not modify the approvals file.
  • always-reject rejects unknown clients immediately and does not modify the approvals file.

Security notes

  • All messages are end-to-end encrypted.
  • The pairing key is exchanged out-of-band through the QR code.
  • Files larger than 2 MB are rejected on read.