Persist HELP CENTER
Help Center

Command Line (persist-cli)

Persist ships a command-line tool, persist-cli, that drives the exact same volume engine as the app. It is a full, scriptable surface for the RAM disk lifecycle — not a reduced toy — but it has a couple of deliberate limits (see below).

Installing it via the app menu

The cleanest way to install the command line tool is from inside the Persist app: open the app menu and choose “Install Command line tool…”. macOS asks for your password, and Persist puts a launcher at:

/usr/local/bin/persist-cli

It is installed as a small shell script that hands off to the CLI binary bundled inside Persist.app — so it always matches the exact version of the app you have, and it automatically picks up app updates. Once it’s on your PATH (/usr/local/bin is usually already there), you can type persist-cli anywhere.

To confirm it works:

persist-cli --version
persist-cli --help

Note: There is no automatic install during the build or during a normal app install/update — the tool only appears if you choose the menu item. That’s intentional.

Which commands exist?

The main verbs mirror the app’s volume operations:

  • persist-cli list — list your volumes (-a/--all includes every registered volume).
  • persist-cli info <ref> — detailed info about one volume.
  • persist-cli create <folder> ... — create a new RAM disk over a folder and mount it.
  • persist-cli mount <ref> — mount a registered RAM disk.
  • persist-cli unmount <ref> — unmount one (frees the memory).
  • persist-cli delete <ref> — delete a volume (move its folder to the Trash by default, or --keep-folder to keep the saved data).
  • persist-cli remote ... — remote storage. Its own sub-commands: list (providers+fields), setup <ref> <provider>, unset <ref>, info <ref>.

A <ref> is either a mount path (e.g. /Volumes/FastScratch) or ramdisk://NAME.

Getting help for each command — each one has a dedicated --help, plus you can ask for help by name:

persist-cli help create
persist-cli help mount
persist-cli help unmount
persist-cli help delete
persist-cli help info
persist-cli help remote
persist-cli help remote setup
persist-cli help remote list
persist-cli help remote unset
persist-cli help remote info

Use persist-cli help <command> for the current, authoritative options and examples — that’s the fastest way to see exactly what a command takes (sizes, flags, aliases). Some things worth knowing up front:

  • A few verbs have abbreviations; list is also ls (e.g. persist-cli ls).
  • Interactive prompts: if you run a command that needs a value you didn’t pass, persist-cli asks. For secrets (like a remote-storage access key) it prompts with echoes disabled and reads from your terminal — nothing you type is shown; for visible text it prompts plainly. If you want to avoid prompts in a script, pass every required field as an argument up front.
  • Output can be --json where that’s useful (see persist-cli help info).

Passing remote-storage credentials via environment variables. For persist-cli remote setup, if you don’t pass the credential pair as arguments, the CLI also looks for them in the environment before prompting. They’re expected as <PROVIDER>_ACCESS_KEY_ID and <PROVIDER>_SECRET_ACCESS_KEY, where <PROVIDER> is the provider’s rclone name (which you can find using rclone remote list) uppercased, any spaces replaced by underscores. For example:

  • AWS S3 — AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • Cloudflare R2 — CLOUDFLARE_ACCESS_KEY_ID and CLOUDFLARE_SECRET_ACCESS_KEY

This lets you script remote setup keeping the secrets out of your shell history. Other secret fields (whose key isn’t the credential pair) are never read from the environment — only from arguments or the hidden prompt.

What the CLI deliberately cannot do

Two things are app-only:

  • It cannot activate a license. There is no license command. If your trial has ended, persist-cli reports the volume cap / license state and tells you to open the Persist app to manage licenses. You activate in the app (or via your existing purchase flow); the CLI then respects it.
  • Periodic background sync and mount-at-launch require the GUI app. The scheduler that periodically refreshes snapshots and the auto-mount-on-launch behavior live in the app, not in the CLI. persist-cli does a single, explicit operation you ask for; it doesn’t schedule anything in the background. If you want periodic backups / auto-mount, keep the app running (e.g. in menu-bar mode) — the CLI can’t replace that on its own.

Both are reflected in each command’s help and error messages, so you’ll be guided to the right place.

A quick end-to-end example

# create a 2 GB disk over ~/FastScratch and mount it
persist-cli create ~/FastScratch --size 2GB

# see what's there
persist-cli ls

# save & unmount it
persist-cli unmount ~/FastScratch

# clean up (moves the backing folder to the Trash)
persist-cli delete ~/FastScratch

(The exact flags are in persist-cli help create — sizes, units, and defaults are shown there.)