The command-line tool

The beamdisk command does from Terminal and from scripts what BeamDisk’s window does: it lists your servers and disks with their state, connects and disconnects, attaches and ejects a disk, turns Connect at login on or off, and checks a server for new disks. Every command can answer in JSON, and each outcome has its own exit code.

The command-line tool is part of BeamDisk Pro, and of the 30-day trial. Without either, every command but help says so and exits with code 5. See Pricing.

Set it up

1. Open BeamDisk’s Settings, then General.
2. Under Command-line tool, click Copy Command. It copies a line that names the tool beamdisk.
3. Paste the line at the end of ~/.zshrc and save it.
4. Open a new Terminal window and type beamdisk help.

The line is an alias for the app itself, so the tool is always the same version as BeamDisk. If BeamDisk isn’t running, a command starts it in the menu bar first; the window doesn’t open.

Commands

Command	What it does
beamdisk status	Whether BeamDisk is connected, then each server and each disk with its state.
beamdisk disks	The disks added to this Mac, with their state, size and Connect at login.
beamdisk servers	The storage servers, with their state, their disks and how many new disks the last check found.
beamdisk connect	Connects to your servers and attaches the disks marked Connect at login, as Connect All does. It waits until every disk has connected or given up, then shows each one.
beamdisk disconnect	Ejects every disk, then disconnects from the servers, as Disconnect All does. If something is using a disk, the others are ejected and BeamDisk stays connected.
beamdisk attach <disk>	Attaches a connected disk, so it’s in Finder.
beamdisk eject <disk>	Ejects a disk. It stays connected, and other computers can use it.
beamdisk connect-at-login <disk> on	Turns Connect at login on for a disk; off turns it off.
beamdisk check <server>	Checks a server for new disks, as Check for New Disks does, and lists them. Add them in BeamDisk’s window.
beamdisk version	BeamDisk’s version, and whether it’s turned on in System Settings.
beamdisk help	The commands. beamdisk help <command>, or any command with --help, shows how to use one.

Name a disk as BeamDisk shows it; put quotes around a name with spaces: beamdisk attach "Team Projects". Capitals don’t matter when only one disk matches. Name a server by its name or its address.

A disk’s state is the one BeamDisk shows, such as Connected, Not attached, Reconnecting or Empty disk: see What a disk’s state means. A disk in trouble also says since when.

Exit codes

Code	Means
0	Done.
1	The command ran but didn’t succeed, for the reason it gives: a disk that couldn’t be ejected because something is using it, or one that didn’t connect.
2	Not a command, or the wrong arguments.
3	No disk or server by that name.
4	BeamDisk couldn’t be started or didn’t answer, or it’s turned off in System Settings.
5	Neither BeamDisk Pro nor the trial.

Messages go to standard output when a command succeeds, and to standard error when it doesn’t.

JSON

Add --json to any command for its answer as JSON on standard output, whatever the outcome. Every answer has ok (true or false), code (the exit code) and, for most commands, message. Times are ISO 8601, sizes are bytes. Keys may be added in later versions, but never renamed or removed.

Key	In the answer to	Holds
status	status, disks, servers, connect, disconnect	connected, enabled (turned on in System Settings), servers and disks.
status.servers[]		name, address, state, detail, since, disks (their names), newDisks (a count), checkedAt.
status.disks[], disk	disk: attach, eject, connect-at-login	name, server, address, target, lun, state, detail, since, connected, attached, readOnly, connectAtLogin, size.
newDisks	check	The new disks, each as its target, LUN number and size.
version	version	version, build, enabled.

$ beamdisk eject Projects --json
{
  "code" : 0,
  "disk" : {
    "address" : "storage.local",
    "attached" : false,
    "connectAtLogin" : true,
    "connected" : true,
    "lun" : 0,
    "name" : "Projects",
    "readOnly" : false,
    "server" : "storage.local",
    "size" : 4000000000000,
    "state" : "Not attached",
    "target" : "iqn.2005-10.org.freenas.ctl:projects"
  },
  "message" : "Projects ejected.",
  "ok" : true
}

In a script

A nightly copy to a disk that’s otherwise ejected, so other computers can use it during the day:

#!/bin/zsh
beamdisk attach Backups || exit 1
rsync -a ~/Projects/ /Volumes/Backups/Projects/
beamdisk eject Backups

A check for a monitoring system, with jq: exit 2 when a disk isn’t connected.

beamdisk disks --json | jq -e 'all(.status.disks[]; .connected)' >/dev/null || exit 2

Mac management tools that run scripts as the logged-in user can use the same commands. BeamDisk runs per user, so a script run as root, or before anyone logs in, can’t reach it.