Help Center

Command Line

RAM Folder includes a command-line tool, ram-folder, that runs the exact same engine as the app: same RAM folders, same saves, same safety rules. It is a complete, scriptable way to manage RAM folders, and it also works without the app’s setup, for example on CI runners.

How do I install it?

In the app, choose RAM Folder › Install Command Line tool…. macOS asks for your password, and RAM Folder installs a launcher at:

/usr/local/bin/ram-folder

The launcher runs the tool bundled inside RAM Folder.app, so it always matches your version of the app and follows its updates. Nothing is installed unless you choose that menu item.

To check it works:

ram-folder --version
ram-folder --help

Which commands are there?

Command What it does
ram-folder list (or ls) Lists mounted RAM folders. --all (-a) includes unmounted ones.
ram-folder info <ref> Shows a RAM folder’s settings, state and, when mounted, its usage. --json for scripts.
ram-folder create <folder> --size <size> Turns a folder into a RAM folder and mounts it. The folder is created if missing.
ram-folder mount <ref> Mounts a RAM folder, loading its folder’s files into RAM.
ram-folder unmount <ref> Saves (if sync is on) and unmounts a RAM folder, freeing its memory.
ram-folder delete <ref> Removes a RAM folder. Deletes its folder by default; --keep saves and keeps it instead. Asks for confirmation; --force skips it, as scripts and CI need.
ram-folder register-license Activates a license key, for the app too.
ram-folder remote … Manages remote storage: list, setup, info, unset.

ram-folder help <command> (for example ram-folder help create or ram-folder help remote setup) shows every option of a command, with its defaults. Add --debug to any command to print detailed logs.

How do I refer to a RAM folder?

A <ref> can be any of:

  • its path: ~/FastScratch;
  • its name: FastScratch;
  • its URL: ram://FastScratch, with spaces and special characters percent-encoded (ram://Fast%20Scratch).

What does create accept?

  • --size (-s): the size, like 512MB, 1GB, 2G or 100M. Required.
  • --name (-n): a custom name. The folder’s name is used by default.
  • --sync-folder / --no-sync-folder: whether changes are saved back into the folder at unmount (the app’s Sync RAM folder). On by default.
  • --mount-at-launch / --no-mount-at-launch: whether the app mounts the RAM folder when it launches (the app’s Mount at launch). On by default.
  • --nobrowse / --no-nobrowse: hide the RAM folder from the Desktop and Finder’s sidebar, or show it. Hidden by default.
  • --enable-fsevents / --disable-fsevents: macOS file-change events on the volume. Off by default here, while the app keeps them on. Turn them on if a tool watches the folder for changes.
  • --file-comparison-method: sizeAndModTime (default) or checksum; see Synchronization.

What happens when apps are using a RAM folder I unmount?

Like the app, ram-folder unmount lists the processes using the RAM folder and asks: [q]uit all, [i]gnore or [c]ancel. In scripts, --force ignores them without asking. --skip-save unmounts without saving, discarding the RAM contents.

Why does it ask for my password? Can it run on CI?

Mounting needs administrator privileges. ram-folder uses the app’s background helper when it is installed and approved, and then needs no password. Otherwise, it runs the mount through sudo and asks for your password in the terminal, before any work starts.

This makes it usable where the app’s setup isn’t possible, such as headless CI runners:

  • the runner needs passwordless sudo, as on GitHub’s macOS runners;
  • running sudo ram-folder … works too: the tool acts as the user who ran sudo, so the RAM folder, its data and its settings stay owned by that user;
  • CI working folders (such as $RUNNER_TEMP or /private/tmp) are not protected by macOS. For protected folders (Desktop, Documents…), the terminal app itself needs Full Disk Access when the helper isn’t used.
# A 4 GB RAM folder for a CI build cache, discarded at the end
ram-folder create "$RUNNER_TEMP/cache" --size 4GB --no-sync-folder
# … build …
ram-folder unmount "$RUNNER_TEMP/cache" --force

How do I activate a license from the Terminal?

ram-folder register-license

It reads the key from the RAMFOLDER_LICENSE_KEY environment variable when it is set, and otherwise asks for it with a hidden prompt. The key is verified and stored where the app reads it, so this licenses the app as well. See Trial & license.

How do I set up remote storage from the command line?

ram-folder remote list                          # providers and their fields
ram-folder remote setup ~/FastScratch aws-s3 --bucket my-bucket --region eu-west-3
ram-folder remote info ~/FastScratch
ram-folder remote unset ~/FastScratch

The provider can be given by its id (aws-s3), its name ("AWS S3") or its rclone name (AWS). Each field can be passed as --<field> (--bucket, --path, --region, --endpoint, --access-key-id, --secret-access-key). A required field you leave out is asked for, with a hidden prompt for secrets.

To keep keys out of your shell history, set the credential pair in the environment instead: <PROVIDER>_ACCESS_KEY_ID and <PROVIDER>_SECRET_ACCESS_KEY, where <PROVIDER> is the provider’s rclone name in uppercase, with spaces replaced by underscores. For example AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for AWS S3, or CLOUDFLARE_ACCESS_KEY_ID for Cloudflare R2. Other secret fields are never read from the environment.

What can’t the command line do?

Two features belong to the app, because they need something running in the background:

  • Periodic saves (Save RAM folder periodically): they start off for a RAM folder made with create; turn them on in the app;
  • Mount at launch: create sets the option, but only the app mounts RAM folders when it launches.

ram-folder performs the one operation you ask for, then exits. Ejects are still saved when the app is closed, since the background helper handles them.

Do the app and the command line see the same RAM folders?

Yes. RAM folders created, changed or deleted with ram-folder appear in the app within moments, and the other way around. While one of them is mounting, unmounting or deleting a RAM folder, the other doesn’t touch it: a mount asked for meanwhile is refused with an error (exit code 1). Try again once the first one is done.

Which exit codes does it use?

Code Meaning
0 Success
1 General error
2 Couldn’t reach the background helper
3 Full Disk Access required
4 Location reserved by macOS
5 Trial limit
6 Saving or syncing failed
8 License needed or invalid
9 Administrator privileges unavailable (sudo refused)

A quick example

# Turn ~/FastScratch into a 2 GB RAM folder
ram-folder create ~/FastScratch --size 2GB

# See what's mounted
ram-folder ls

# Save and unmount it (by path, name or URL)
ram-folder unmount ram://FastScratch

# Mount it again: the saved files come back
ram-folder mount FastScratch

# Stop using it, keeping the folder and its files
ram-folder delete FastScratch --keep