Command line

The communal command runs Communal on a computer with no screen (a home server, a NAS) and controls it. It’s the same engine as the app.

Install on Linux

The quickest way installs or upgrades to the latest release (it needs Node.js 24 or later):

curl -fsSL https://hypnopompia.github.io/Communal/install.sh | sh -s -- headless

Or by hand: download communal-<version>-linux-x64.tar.gz (or -arm64) from the latest release. It needs Node.js 24 or later.

tar xzf communal-*-linux-x64.tar.gz
cd communal-*-linux-x64
sudo ./install.sh

That installs Communal to /opt/communal, adds /usr/local/bin/communal, and starts the communal systemd service as its own user with its data in /var/lib/communal. Settings such as the UDP port or upload limits go in /etc/communal/communal.env.

Run commands as the service user, which owns the data:

sudo -u communal communal hub add wss://hub.example.com/v1 --name "Home server"
sudo -u communal communal share add /srv/media/Movies --name Movies
sudo -u communal communal acl set Movies/ hub
sudo -u communal communal status

The folders you share must be readable by the communal user. A Docker image is also available; see the repository’s docker/ folder.

With the desktop app

When no communal daemon is running, the command controls the open desktop app instead, as long as Settings › AI agents › Allow control from the CLI and AI agents is on. Running from a checkout of the source: pnpm --filter @communal/cli dev -- status.

Setting up

Command	What it does
`communal hub add <url> --name <name>`	Join a hub (the first one creates your account). `hub list`, `hub remove`.
`communal daemon`	Run the engine in the foreground (what the service runs).
`communal status`	This device, its hubs and indexing progress.
`communal check`	Check the install: native modules, ffmpeg, the trash helper.
`communal netcheck`	NAT type per hub, router port mapping, IPv6, carrier-grade NAT.

Command	What it does
`communal share add <path> --name <name>`	Share a folder. `share list`, `share remove <name>`, `share hubs <name> [hub ids…]`.
`communal acl set <path> <audience>`	Who can see a folder (ending in `/`) or file: `me`, `hub`, `users:<ids>` or `groups:<ids>`. Add `--hub` when on several hubs.
`communal acl clear <path>`	Remove a rule so the path follows its folder again. `acl list` shows every rule.

People and groups

Command	What it does
`communal people search <name>`	Find people on a hub.
`communal people request\|accept\|remove <user_id>`	Connect, accept a request, or disconnect.
`communal people list`	Connections and pending requests.
`communal people verify <user_id> [--confirm]`	Show the safety code to compare; `--confirm` marks them verified.
`communal group set <name> [members…]`	Create a group from connections (`--id` replaces one). `group list`, `group delete`.

Managing a hub

On a hub you administer (the first account on a hub is its admin). Add --hub if you administer more than one.

Command	What it does
`communal admin users [--waiting\|--banned]`	Everyone on the hub, with their computers and how much each shares.
`communal admin approve\|unban <user_id>`	Let in someone who’s waiting, or lift a ban.
`communal admin ban <user_id> [--reason]`	Sign someone out of the hub for good. Admins can’t be banned here.
`communal admin settings [--join-mode open\|approval] [--name\|--clear-name]`	Show or change the hub’s name and who can join, and its limits: `--signups-per-hour`, `--max-files` (per device), `--max-devices` (per account). 0 means no limit.
`communal admin graph`, `communal admin log`	Who’s connected to whom, and every admin action.

Finding and downloading

Command	What it does
`communal search <words…>`	Search every hub. `--kind`, `--min-size`, `--online`, `--seen today\|week\|month`, `--from connections\|verified`, `--json`.
`communal browse <hub> <device> [path]`	List a folder on a computer you can see.
`communal peek <hub> <device> <hash>`	Show the start of a text or code file.
`communal thumbs <hub> <device> <path>`	Fetch a folder’s thumbnails into the cache.
`communal get <hash>`	Download by content hash from every online source. `--name`, `--dest <folder>`, `--to <destination>`, `--on <device>`.
`communal get-folder <device> <path>`	Download a folder and the folders inside it, once. Files you already have are copied, not downloaded. `--dest`, `--to`, `--on`, `--hub`.
`communal download-dir [folder]`	Show or change where downloads go. `--reset` goes back to the usual one.
`communal transfers`	Downloads, with the reason and tips when a source can’t be reached. `--clear` removes finished ones from the list (the files stay). `communal cancel <id>`. Both take `--on <device>`.
`communal log`	Who downloaded what from this computer (kept locally only). `--user`, `--path`, `--clear`.

Subscriptions

Command	What it does
`communal subscribe <device> <path> --no-mirror-deletes`	Follow a folder. You must say `--mirror-deletes` or `--no-mirror-deletes`. Also `--dest`, `--to`, `--flat`, `--hub`, `--on`.
`communal subscriptions [list\|set\|remove]`	List, change (`set <id>` with `--pause`, `--resume` or `--mirror-deletes on\|off`) or remove subscriptions. Add `--on <device>` for another device’s.
`communal sync [on [folder]\|off]`	The synced folder: one folder kept the same on all your computers (default `~/Communal`). Run `on` on each computer. On its own, `communal sync` shows which computers it’s in step with.

Destinations

Named folders on this device that downloads can go into, like Movies or TV. Downloads is built in and is the downloads folder. A folder you download or subscribe to goes inside the destination under its own name.

Command	What it does
`communal dest [list]`	This device’s destinations and their folders.
`communal dest add <name> <folder>`	Add one, e.g. `communal dest add Movies /srv/media/movies`.
`communal dest set <name> <folder>`	Point a destination at another folder. `--rename` renames it too.
`communal dest remove <name>`	Forget it. The folder and its files stay.
`--to <name>`	On `get`, `get-folder` and `subscribe`: save into a destination instead of the downloads folder. With `--on`, it names one of that device’s destinations.

Remote control

Your devices can download for each other: a laptop or phone sends a film to the media server, or subscribes it to a friend’s folder. Only the request goes through the hub, sealed so the hub can’t read it, and the files still travel directly. A device takes requests only once you allow it, and other devices can only name its destinations, never a folder.

Command	What it does
`communal remote [status]`	Whether this device takes requests, and your other devices: online, and whether they do, with their destinations.
`communal remote allow\|deny`	Let your other devices start downloads here, or stop them (off to begin with).
`communal remote downloads on\|off`	Off: your other devices can only save into the destinations here, not the downloads folder, and must name one.
`--on <device>`	Another of your devices, by name or id, does it instead: on `get`, `get-folder`, `subscribe`, `subscriptions` (list, set, remove), `transfers` and `cancel`.

Setting up a media server, on the server:

sudo -u communal communal dest add Movies /srv/media/movies
sudo -u communal communal dest add TV /srv/media/tv
sudo -u communal communal remote allow
sudo -u communal communal remote downloads off

Then from your laptop:

$ communal remote
this device: doesn't take downloads from your other devices
  Media server             linux    takes requests  d_rr75yzpn5xtcvtlpiilx2nluta
    destinations: Movies, TV
$ communal get-folder d_4kq… "Films/Night Bus (2024)" --on "Media server" --to Movies
$ communal subscribe d_4kq… "Shows/Harbor Lights" --on "Media server" --to TV --no-mirror-deletes
$ communal subscriptions --on "Media server"
$ communal transfers --on "Media server"

The desktop and Android apps do the same from their Download menus, Subscriptions and Transfers (see the app guide).

Devices and recovery

Command	What it does
`communal devices [list]`	Your computers.
`communal devices add`	Make a link code for a new computer or phone, then approve it. `--yes` approves whoever claims the code.
`communal devices requests\|approve\|deny`	Computers waiting for approval.
`communal devices revoke <device>`	Remove a lost computer everywhere (can’t be undone).
`communal link <code> --hub <url>`	Add this computer to your account (works with the daemon stopped).
`communal recovery export --out <file>` or `--words`	Save the recovery key (on the computer that holds the account’s root key).
`communal restore <file>` or `--words --hub <url>`	Restore your account onto a fresh computer.

Passphrases and words are read without echo, or from COMMUNAL_RECOVERY_PASSPHRASE / COMMUNAL_RECOVERY_WORDS.

Settings

Variable	Meaning
`COMMUNAL_DATA`	Data folder (default `~/.communal`).
`COMMUNAL_PEER_PORT`	UDP port for peers (0: any). Forward it on your router for the best reachability.
`COMMUNAL_ADVERTISE_ADDR`	Extra `ip:port` others can reach this computer at (a port forward, a public IP).
`COMMUNAL_UPNP=false`	Don’t ask the router to open the port.
`COMMUNAL_UPLOAD_KBPS`, `COMMUNAL_MAX_UPLOADS`, `COMMUNAL_LAN_ONLY`	Upload limits (changes made with the API or app take precedence).
`COMMUNAL_DOWNLOADS`	Where downloads land.

The command for AI assistants, communal mcp, is covered under AI agents.