Shellular Docs

Get started in just 3 steps:

  1. Run npx shellular
  2. Scan the QR code with the Shellular app
  3. Approve the device
Quick start npm 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.

If you are comparing mobile remote development setups, read Shellular vs Claude Remote Control for the short version of where Shellular fits.

Requirements

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

On Windows

The npx shellular shorthand used throughout these docs is for macOS and Linux. On Windows, install the CLI globally once:

windows 
npm i -g shellular

After that, run every command in these docs without the npx prefix — use shellular, shellular start, shellular clients, and so on.

Quick start

On macOS and Linux, start the CLI directly with npx — no install needed:

macOS / Linux 
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 before it can connect.

On Windows, install globally first and drop the npx prefix — see On Windows above.

Background mode

To keep Shellular running after you close your terminal:

terminal 
npx shellular start

In daemon mode, clients are not approved interactively. Run shellular clients to review pending devices and approve them from any terminal.

Stop the host when you are done:

terminal 
npx shellular stop
Note

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

Start on boot

To have the host come back automatically after a reboot, Shellular can install a system startup script. Under the hood this wraps PM2's startup command, which generates and configures the right init script for your platform (systemd, launchd, etc.).

Prerequisite

The daemon must already be running before these commands work — start it first with shellular start. The startup script captures the currently running host so it can be resurrected on boot.

Install the startup script:

terminal 
npx shellular startup

This registers Shellular to launch on boot. You may be prompted to run a command with elevated privileges (sudo) to complete the install, since it writes a system-level init script.

Remove the startup script when you no longer want Shellular to auto-start:

terminal 
npx shellular unstartup

Commands

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
shellular users List, add, or remove accounts on the connection allowlist (alias for shellular users list)
shellular users add <email-or-id> Allow an account, by email or user ID, to connect
shellular users remove <email-or-id> Revoke an account and disconnect all of its devices
shellular startup Generate and install a boot startup script so the daemon restarts on reboot (wraps PM2)
shellular unstartup Remove the boot startup script created by startup (wraps PM2)

Options

Global flags that apply to all commands:

--server <url> default: wss://api.shellular.dev
Relay server WebSocket URL
--dir <path> default: $HOME
Root directory exposed to the client
--unknown-clients <policy> default: requires-approval
How unknown clients are handled: always-reject, always-allow, or requires-approval
--no-qr default: false
Skip printing the pairing QR code on start. Useful once your phone has connected at least once — you avoid re-displaying the QR every time, which is better for privacy on shared or visible screens

shellular clients flags

--delete <clientId>
Delete a known client from the store

Unknown client approval

--unknown-clients only applies to devices not already in the local approvals file. Once a client is approved or rejected it is remembered.

requires-approval

Default. In foreground mode the CLI asks interactively. In daemon mode the connection is held pending until you run shellular clients.

always-allow

Accepts unknown clients immediately without writing to the approvals file.

always-reject

Rejects unknown clients immediately without writing to the approvals file.

Account allowlist

Client approval works per device. The users command adds a second, higher gate that works per account — the Shellular account you sign in with in the app, identified by its email or stable user ID.

How it works

  • Off by default. An empty allowlist gates nothing — any approved device connects as usual.
  • Adding the first account turns it on. From then on, only listed accounts may connect.
  • Unauthenticated clients are always rejected while the allowlist is active.
  • It's checked before device approval. An allowlisted account lets in all of its devices — even brand-new ones — with no unknown-client prompt. Removing it disconnects every one of them at once.

Commands

shellular users list Show the allowed accounts. Running shellular users alone does the same.
shellular users add <email-or-id> Allow an account to connect, by email or user ID.
shellular users remove <email-or-id> Revoke an account and disconnect all of its devices.
terminal 
npx shellular users add you@example.com
Where to find your email or user ID

Under the Account tab in the Shellular app, or at app.shellular.dev.

Security

  • End-to-end encrypted
    Data is encrypted on your device before it hits our server, and decrypted only on your phone. The relay just passes it through.
  • TLS in transit
    All traffic runs over TLS — no unencrypted connections at all.
  • Key never leaves your device
    Pairing is done by scanning a QR code that contains the encryption key. It's never transmitted through any network.
  • Only your devices can connect
    Every new device must be approved by you on the host before it can connect.
Learn more about our security model