# The command-line tool

> The beamdisk command, part of BeamDisk Pro and the trial: list servers and disks with their state, connect and disconnect, attach and eject a disk, Connect at login, check a server for new disks, with JSON output and exit codes for scripts.

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](https://beamdisk.app/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](https://beamdisk.app/docs/troubleshooting/disk-states/). 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.