Commands
Every command supports --help for the full flag list, and tab completion is available after
installation.
Global Flags​
| Flag | Purpose |
|---|---|
--manager-endpoint | Manager API endpoint. Defaults to the value saved with config set. |
--api-token | API authentication token |
-v, --verbose | Verbose output |
--log-level | debug, info, warn, error, fatal |
--version | Print the build version, Git SHA, and build date |
config​
Store the CLI's local settings.
mass-ctl config set manager-endpoint https://<head-node-ip>:30083
mass-ctl config get manager-endpoint
mass-ctl config unset api-token
Keys: manager-endpoint, api-token.
login / logout​
Obtain and clear a user certificate. See Authentication Setup.
mass-ctl login --username alice
mass-ctl login --username alice --validity-hours 168
mass-ctl logout
machine register​
Register this host so every user on it can mount volumes with one long-lived certificate.
sudo mass-ctl machine register
| Flag | Purpose |
|---|---|
--hostname, --fqdn, --ip | Override the auto-detected values |
--cert-dir | Where to save the certificate (default /etc/boostx-sds/certs) |
--username, --password, --source | Authenticate the request explicitly instead of using the saved session |
mount​
Mount a volume as a POSIX filesystem. The volume ID is shown in the Dashboard on the volume's detail dialog, together with a ready-to-copy command.
sudo mass-ctl mount --volume-id <volume-id> --mount-point /mnt/data
Options:
| Flag | Description |
|---|---|
--volume-id | The volume to mount (required) |
-m, --mount-point | Local directory to mount into (required) |
--read-only | Mount read-only |
--allow-other | Make the mount accessible to every user on the host, not just the invoking user. POSIX ownership and permissions are still enforced per user. Required for machine-identity mounts. |
--no-fstab | Temporary mount that does not survive a reboot. Also the only way to mount without root. |
--disable-caching | Disable caching (enabled by default) |
--cert, --key, --ca | Certificate paths, overriding config and auto-discovery |
Reboot recovery is the default​
Mounting registers the mount for reboot recovery, so it comes back automatically after the host restarts — one reboot restores every user's mounts at once. Root registers directly; a non-root user's registration goes through a helper installed with the package, so non-root users can mount their own volumes without administrator help.
Pass --no-fstab for an explicitly temporary mount.
--fstab is deprecated and now a no-op — reboot-recovery registration is the default. Existing
mount records from earlier versions are migrated automatically when the package is upgraded.
Established mounts also recover on their own when a node's storage service restarts; the mount is re-armed so the next access works without rebooting the client.
unmount​
sudo mass-ctl unmount --mount-point /mnt/data
dsync​
Copy or synchronize a directory tree into a mounted volume using the bundled MPI-parallel data mover. Everything it needs ships with the client package.
mass-ctl dsync --source /data/legacy --target /mnt/data/incoming
| Flag | Description |
|---|---|
--source | Source path to copy from (required) |
--target | Target path to sync into (required) |
--ncpu | Number of MPI processes; defaults to half the node's CPU cores |
--mpi-prefix | MPI installation prefix, if you need to override the bundled one |
Progress is shown as it runs, with a completion notice when all data has been copied.
migration​
Copy data from an external source into a volume. See Migrating Data In.
mass-ctl migration create --volume-id <id> --source nfs \
--nfs-server 10.0.0.5 --nfs-export /export/data
mass-ctl migration list --phase Copying
mass-ctl migration progress <id> --watch
mass-ctl migration describe <id>
mass-ctl migration cancel <id>
mass-ctl migration summary <id>
Source types: s3, nfs, local. Unlike the Dashboard, the CLI supports S3 sources.
backup​
mass-ctl backup cancel <backup-id>
Cancels an in-flight backup. The backup is marked failed and its partial data is cleaned up. Create, trigger, and restore backups from the Dashboard — see Managing Protection.
connect​
Print connection information for an object-store volume, optionally with example code.
mass-ctl connect <volume-id>
mass-ctl connect <volume-id> --show-example --language python
env​
Print environment variables that tune I/O for the current shell session. Use with eval.
# Optimize for large sequential I/O (maximum bandwidth) — the default
eval $(mass-ctl env --bandwidth)
# Optimize for metadata-intensive workloads (many small files)
eval $(mass-ctl env --metadata)
# Standard mode, no optimization
eval $(mass-ctl env --standard)
| Mode | Best for |
|---|---|
--bandwidth | Large file reads and writes, AI training data |
--metadata | Many small files, checkpointing |
--standard | Baseline behavior with no optimization |
These are boolean flags, not values passed to a --mode option.
completion​
mass-ctl completion bash
mass-ctl completion zsh
mass-ctl completion fish
mass-ctl completion powershell
bash and zsh completion are installed automatically by the package.
Administrative Commands​
Storage and identity management (volumegroup, volume, identity, policy, node, drive,
audit, cluster, auth-config, reset-admin-password) is not part of the client package. Those
commands ship in the administrative build installed on the appliance.
For day-to-day administration use the Dashboard — see the User Guide.
attach and status remain for backward compatibility and are deprecated. Use the Dashboard, or
volume get in the administrative build, instead of status.