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 --helpWhich 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, like512MB,1GB,2Gor100M. 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) orchecksum; 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 ransudo, so the RAM folder, its data and its settings stay owned by that user; - CI working folders (such as
$RUNNER_TEMPor/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" --forceHow do I activate a license from the Terminal?
ram-folder register-licenseIt 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 ~/FastScratchThe 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:
createsets 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