Command reference

Every nearshare command, for scripts, keyboard shortcuts and terminal use.

Most commands talk to the running NearShare app, so open it first. The exceptions are noted below.

Commands

Command	What it does
nearshare gui	Opens the NearShare window
nearshare status	Shows visibility, the device name, how many devices are nearby and the Bluetooth state
nearshare on	Makes this computer visible. Starts the app if it is not running.
nearshare off	Hides this computer from nearby devices
nearshare toggle	Switches visibility and shows a notification. Starts the app if it is not running.
nearshare peers	Lists nearby devices that can receive right now
nearshare send FILE... [--to NAME]	Sends files to a nearby device. Works without the app running.
nearshare send-picker FILE...	Opens the Send with NearShare device picker for the files
nearshare rename IP_OR_NAME NAME	Gives a nearby device a permanent name
nearshare forget [IP_OR_NAME]	Removes a saved name; with no argument, lists saved names

When the app is not running, off, status and peers print NearShare app is not running and exit with an error.

Options

Option	Commands	What it does
--json	on, off, toggle, status, peers, send	Prints the raw JSON response, for scripts
--to NAME	send	The device to send to. Optional when exactly one device is nearby.

In nearshare status --json, the ble field is on, off, or unavailable: followed by the reason.

How send works without the app

nearshare send starts a temporary copy of NearShare with no window, looks for the device for up to 20 seconds, prints the PIN as soon as the connection produces one, and sends. The device must have its Quick Share receive screen open.

Examples

nearshare status
nearshare peers
nearshare send ~/Pictures/holiday.jpg --to "Pixel 8"
nearshare send report.pdf notes.txt        # only one device nearby
nearshare rename "Phone (6SWJ)" "My phone"
nearshare forget

Keyboard shortcut

Action	Keys
Toggle visibility	Ctrl + Alt + N, once bound

The PPA package binds it through Finish setup. With the snap, add a custom shortcut for nearshare toggle in GNOME Settings; see Visibility and background.

Files and folders

What	Where
Received files	~/Downloads
Saved device names	~/.config/nearshare/known_devices.json (PPA package)
Window preferences	~/.config/nearshare/ui-state.json (PPA package)

The snap keeps its settings inside its own snap folder.

Network use

Purpose	Protocol
Finding devices	mDNS on UDP port 5353, on your local network
Transfers	TCP, on a port chosen when NearShare starts
Wake-up signal	Bluetooth Low Energy, when available

Next steps

• Troubleshooting and FAQ
• Send files