Package Exports

shellular
shellular/dist/main.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (shellular) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Shellular CLI

Host agent for Shellular — connects your dev machine to the Shellular relay so you can access your environment remotely from the Shellular app.

Features

Terminal — full PTY sessions; terminals survive CLI reconnects and are only killed on clean exit
Filesystem — browse, read, write, rename, and delete files within the working directory
Ports — list and kill processes by port
Proxy — HTTP and WebSocket proxying to local services
System monitor — CPU, memory, and battery streaming
Agents VIA ACP — use agents like Codex, Claude Code, OpenCode, Copilot CLI, Pi
End-to-end encryption — all messages are encrypted with libsodium; the pairing key is exchanged out-of-band via QR code

Requirements

Node.js 20+
macOS / Linux / Windows

Quick Start

npx shellular

Scan the QR code printed in the terminal with the Shellular app to connect.

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

To run Shellular in the background instead:

npx shellular start

When Shellular is running in daemon mode, unknown clients are not approved interactively. Use npx shellular clients to review and approve them.

Stop the background host when you are done:

npx shellular stop

Note: Only one instance of Shellular can run at a time per machine. Starting a second instance will exit immediately.

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 restart`	Restart 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>`	OS home directory (`$HOME`)	Root directory exposed to the client
`--unknown-clients <policy>`	`requires-approval`	How unknown clients are handled: `always-reject`, `always-allow`, or `requires-approval`

--unknown-clients only applies to clients 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 when a new client tries to connect.
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.

Development

pnpm install
pnpm run dev                          # foreground watch mode
pnpm run dev -- --dir ~/projects      # foreground with custom options
pnpm run dev -- start                 # background host
pnpm run dev -- start --dir ~/projects # background host with custom options

Build

pnpm run build   # tsc + tsup

Output goes to dist/. Entry point: dist/main.js.

Format

pnpm run format

Security

Filesystem access is restricted to the --dir root (path traversal is rejected).
Files larger than 2 MB are rejected on read.

License

Source-Available License