RAM Folder HELP CENTER
Help Center

Command Line (ram-folder)

RAM Folder ships a command-line tool, ram-folder, that drives the exact same volume engine as the app. It is a full, scriptable surface for the RAM folder 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 RAM Folder app: open the app menu and choose “Install Command Line tool…”. macOS asks for your password, and RAM Folder puts a launcher at:

/usr/local/bin/ram-folder

It is installed as a small shell script that hands off to the CLI binary bundled inside RAM Folder.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 ram-folder anywhere.

To confirm it works:

ram-folder --version
ram-folder --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:

  • ram-folder list — list your volumes (-a/--all includes every registered volume).
  • ram-folder info <ref> — detailed info about one volume (--json for scripting).
  • ram-folder create <folder> ... — create a new RAM folder over a folder and mount it.
  • ram-folder mount <ref> — mount a registered RAM folder.
  • ram-folder unmount <ref> — unmount one (frees the memory). --skip-save unmounts without running the save.
  • ram-folder delete <ref> — delete a volume. By default it deletes the on-disk folder too; --keep saves the RAM folder’s data and keeps the folder (mirroring the app’s “Keep folder” action). --force skips the confirmation prompt.
  • ram-folder remote ... — remote storage. Its own sub-commands: list (providers+fields), setup <ref> <provider>, unset <ref>, info <ref>.

A <ref> is any one of:

  • a mount path (e.g. /Volumes/FastScratch),
  • a volume name (e.g. FastScratch), or
  • the canonical ram://NAME URL (e.g. ram://Fast%20Scratch — names are percent-encoded).

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

ram-folder help create
ram-folder help mount
ram-folder help unmount
ram-folder help delete
ram-folder help info
ram-folder help remote
ram-folder help remote setup
ram-folder help remote list
ram-folder help remote unset
ram-folder help remote info

Use ram-folder 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. ram-folder ls).
  • Interactive prompts: if you run a command that needs a value you didn’t pass, ram-folder 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 ram-folder help info).

Passing remote-storage credentials via environment variables. For ram-folder 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, ram-folder reports the license state and tells you to open the RAM Folder 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. ram-folder 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
ram-folder create ~/FastScratch --size 2GB

# see what's there
ram-folder ls

# save & unmount it
ram-folder unmount ~/FastScratch

# unmount a volume by name instead of path
ram-folder unmount FastScratch

# clean up (deletes the backing folder too; add --keep to save & keep it)
ram-folder delete ~/FastScratch

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