CLI reference
Install the mountable.io CLI. Every command and flag, --json output, exit codes, retries, and the MOUNTABLE_API_KEY and other environment variables.
Install
curl -fsSL https://mountable.io/install.sh | sh # standalone binary
npx -y mountable-cli version # or npm
uvx mountable version # or PyPIThe installer checks the package against npm's sha512 and installs to
~/.local/bin. Set MOUNTABLE_VERSION for a specific version or
MOUNTABLE_INSTALL_DIR for another directory. It never uses sudo.
All three channels run the same self-contained Linux/macOS CLI (x64 and
arm64); mounting downloads nothing else. With npm or PyPI, use
npx -y mountable-cli or uvx mountable in place of mountable below.
See Contract and limits for verified platforms.
Commands
mountable login
mountable logout
mountable orgs list
mountable fs list [--org ORG_ID]
mountable fs create NAME [--spending-cap-cents N] [--mutations-per-minute N]
[--byte-quota BYTES] [--entry-quota N] [--org ORG_ID]
mountable fs get FS_ID [--org ORG_ID]
mountable fs update FS_ID [--spending-cap-cents N|none] [--mutations-per-minute N|none]
[--byte-quota BYTES] [--entry-quota N] [--org ORG_ID]
mountable fs usage FS_ID [--org ORG_ID]
mountable fs delete FS_ID [--org ORG_ID]
mountable ticket create FS_ID [--ro] [--idempotency-key KEY] [--max-duration DURATION]
mountable sessions list FS_ID [--org ORG_ID]
mountable sessions revoke SESSION_ID
mountable files write FS_ID PATH [--from FILE] [--if-match ETAG] [--if-none-match]
mountable files read FS_ID PATH [--to FILE]
mountable files delete FS_ID PATH [--if-match ETAG]
mountable files list FS_ID [PATH] [--after NAME] [--limit N]
mountable files changes FS_ID [--cursor CURSOR] [--wait SECONDS]
mountable webhooks create FS_ID URL [--path-prefix PREFIX] [--org ORG_ID]
mountable webhooks list FS_ID [--org ORG_ID]
mountable webhooks delete FS_ID WEBHOOK_ID [--org ORG_ID]
mountable webhooks rotate-secret FS_ID WEBHOOK_ID [--org ORG_ID]
mountable webhooks enable FS_ID WEBHOOK_ID [--org ORG_ID]
mountable api-keys create NAME [--expires-in-days N] [--filesystem FS_ID [--ro]] [--org ORG_ID]
mountable api-keys list [--org ORG_ID]
mountable api-keys revoke KEY_ID [--org ORG_ID]
mountable s3-keys create FS_ID NAME [--ro] [--expires-in-days N] [--org ORG_ID]
mountable s3-keys list FS_ID [--org ORG_ID]
mountable s3-keys revoke FS_ID ACCESS_KEY_ID [--org ORG_ID]
mountable grants list FS_ID [--org ORG_ID]
mountable grants set FS_ID member|group|api_key PRINCIPAL_ID ro|rw [--org ORG_ID]
mountable grants delete FS_ID GRANT_ID [--org ORG_ID]
mountable mount [--ro] FS_ID DIR
mountable mount --ticket-stdin DIR
mountable unmount DIR
mountable mcp
mountable version
mountable licensesEvery command also takes --json; see Output.
The key, grant and fs delete commands need CLI 0.10.0 or later.
Authentication and organisation
- People:
mountable loginsigns this machine in. - Provisioning services: set
MOUNTABLE_API_KEY=mtblm_…, a management key. It creates and deletes filesystems, sets their limits, and manages API keys, S3 keys and grants. - Backends and agents: set
MOUNTABLE_API_KEY=mtbl_…, an API key. It works with files: tickets, sessions, thefilescommands and webhooks. - Either key is used instead of the login and belongs to one organisation,
which the commands use. A command with the other kind fails with
management_key_requiredorapi_key_required. - Sandboxes: need no credentials, only a one-time ticket on stdin.
Commands that work inside an organisation take --org ORG_ID, then
MOUNTABLE_ORG, then the only organisation the caller has. With several,
they fail with org_required.
mountable login
mountable loginSigns this machine in with a device code. The CLI prints a URL and a short
code; open the URL, check that the console shows the same code, and choose
Approve. The CLI keeps its tokens in an owner-only file in your user
configuration directory.
The login lasts up to thirty days. The CLI renews its short-lived access
tokens automatically while that login remains valid. Run mountable login
again after it expires or is revoked; use the console to administer the
organisation, team, keys and billing.
mountable orgs list
Lists the caller's organisations. A key has exactly one.
mountable fs
mountable fs list
FS_ID=$(mountable fs create agent-workspace)
USER_FS=$(mountable fs create user-42 --spending-cap-cents 500 --mutations-per-minute 120)
mountable fs get "$USER_FS"
mountable fs update "$USER_FS" --spending-cap-cents 2000 --mutations-per-minute none
mountable fs usage "$FS_ID"fs listlists filesystems. An API key sees only those it has a grant on.fs create NAMEcreates a filesystem and prints its ID. Names need not be unique. The limit flags set the filesystem's limits in the same request. Give the backend's API key access withgrants set, or create a key for it withapi-keys create --filesystem.fs get FS_IDshows the filesystem and its four limits.fs update FS_IDchanges only the limits given and prints the result likefs get;noneremoves the spending cap or the custom rate. It needs at least one flag.fs usage FS_IDshows stored bytes and files against the quotas, the traffic over 30 days, and with--jsonthis month'sreserved_cents.fs delete FS_IDdeletes the filesystem at once, with its files, mount sessions, webhooks and S3 keys. It cannot be undone.
Creating, changing and deleting filesystems take a management key or an
owner's or admin's login; the API checks the ranges and answers
invalid_request for a value outside them.
mountable api-keys, s3-keys and grants
BACKEND_KEY=$(mountable api-keys create backend --filesystem "$FS_ID")
mountable api-keys list
mountable api-keys revoke "$KEY_ID"
S3_SECRET=$(mountable s3-keys create "$FS_ID" duckdb --ro --expires-in-days 90)
mountable s3-keys list "$FS_ID"
mountable s3-keys revoke "$FS_ID" "$ACCESS_KEY_ID"
mountable grants list "$FS_ID"
mountable grants set "$FS_ID" api_key "$KEY_ID" rw
mountable grants delete "$FS_ID" "$GRANT_ID"These take a management key or an owner's or admin's login.
api-keys create and s3-keys create print only the new key's secret on
stdout, shown this once, and its ID (for an S3 key, the access key ID) on
stderr; --json prints the whole answer, secret included. A key lasts 30
days unless --expires-in-days says otherwise (at most 365), and never
beyond the management key that created it. api-keys create --filesystem
limits the key to that filesystem, read-write or with --ro read-only.
An S3 key works at https://s3.mountable.io with the filesystem
ID as the bucket. grants set gives a member, group or API key access, or
changes its mode.
mountable ticket create
mountable ticket create "$FS_ID" --idempotency-key job-42
mountable ticket create "$FS_ID" --ro --idempotency-key job-43 --json
mountable ticket create "$FS_ID" --ro --max-duration 720hCreates a mount session and prints its one-time ticket, for a sandbox to
mount with (--ro for read-only). The ticket works once and expires within
minutes. Without --idempotency-key, the CLI generates a key and prints it
to stderr before sending; see Retries.
--max-duration sets how long the mount session may last, in whole seconds
written as a Go duration such as 12h or 720h. It defaults to 12 hours, and
it can be at most 365 days and no longer than the API key or login that
creates it. For a long-running VM mount, give a long duration and restart the
mount with a new ticket when the session ends.
mountable sessions
mountable sessions list "$FS_ID"
mountable sessions revoke "$SESSION_ID"sessions list lists a filesystem's live mount sessions; an API key sees
those it created. sessions revoke revokes one; its mount stops working
within seconds.
mountable files
Reads and writes files over HTTPS, without mounting.
Each command asks for a one-hour token session for the filesystem
(read-only for read, list and changes), uses it for the one request,
then revokes it.
mountable files write "$FS_ID" notes/plan.md --from plan.md
printf '# Plan\n' | mountable files write "$FS_ID" notes/plan.md --if-none-match
mountable files read "$FS_ID" notes/plan.md > plan.md
mountable files read "$FS_ID" notes/plan.md --to plan.md --json
mountable files list "$FS_ID" notes
mountable files changes "$FS_ID" --json # the current cursor
mountable files changes "$FS_ID" --cursor "$CURSOR" --wait 25
mountable files delete "$FS_ID" notes/plan.md --if-match "$ETAG"files writesends--from FILE, or stdin, as the whole file and prints its path, ETag and size (--json: its FileInfo).--if-match ETAGwrites only if the file still has that ETag;--if-none-matchonly if nothing exists at the path. A failed condition isprecondition_failed, whose error holds the file'scurrent_etag.files readwrites the file's bytes to stdout, or to--to FILE, which is replaced only once the whole file arrived (with mode0600).--jsonneeds--toand prints the FileInfo. A read to stdout that breaks off exits with1, and the bytes already written are incomplete.files listprints one directory page: type, size, modified time and path. When there are more entries, stderr says which--afterto pass.files changeswithout--cursorprints the current cursor at once; with it, it waits up to--waitseconds (default 25) for the changes after it. Events areTYPE PATHlines; the next cursor goes to stderr. See following changes.files deletedeletes a file, a symbolic link or an empty directory.
Each request has 60 seconds, the transfer included, so for very large files use the SDKs or a mount.
mountable webhooks
WEBHOOK_SECRET=$(mountable webhooks create "$FS_ID" https://example.com/hooks/mountable --path-prefix /tickets)
mountable webhooks list "$FS_ID"
WEBHOOK_SECRET=$(mountable webhooks rotate-secret "$FS_ID" "$WEBHOOK_ID")
mountable webhooks enable "$FS_ID" "$WEBHOOK_ID"
mountable webhooks delete "$FS_ID" "$WEBHOOK_ID"create and rotate-secret print only the webhook's
secret (whsec_…) on stdout, shown this once, and the webhook's ID on
stderr; --json prints the whole answer, secret included. list shows each
webhook's state, path prefix, URL and last failure. Every webhook command
needs read-write access to the filesystem.
mountable mount
mountable mount k5q2ztr4mvd7wn3xa6jhebcyfu ~/work
mountable mount --ro k5q2ztr4mvd7wn3xa6jhebcyfu ~/workCreates a mount session with your login (read-write, or read-only with
--ro), exchanges its ticket, and mounts the filesystem at DIR, which must
be an existing, writable directory. The
command stays in the foreground and renews the session certificate every few
minutes. Stop it with Ctrl-C or mountable unmount DIR: pending writes are
finished and the filesystem is unmounted cleanly.
On Linux it mounts through FUSE; on a Mac, through the NFS client built into
macOS, with nothing else to install (Mount on a Mac).
When the CLI observes that its session was revoked or expired, it aborts:
every further operation in DIR fails, the mount is detached, and the
command exits with an error. Writes not yet committed are lost, since the
service no longer accepts them.
Revocation is not instantaneous: see the server's
admission bound. After a privilege
change, make a new session with the mode you still hold rather than retrying
the revoked mount indefinitely.
printf '%s\n' "$MOUNTABLE_TICKET" | mountable mount --ticket-stdin --json /mnt/workMounts with a ticket read from stdin instead of your login. The ticket already names the filesystem and mode. This is how a sandbox mounts with a session your backend created; see Agents and Mount from a sandbox.
With --json, mount writes JSON lines as it progresses:
{"event":"mounted","path":…,"filesystem_id":…,"mode":…} once the mount is
usable, and
{"event":"unmounted","reason":"signal|unmount|revoked|expired|error","detail":…}
when it ends. Wait for mounted before using the directory.
mount keeps stderr quiet. Without --json it says
mountable: mounted at DIR. After that it speaks only when something
needs you: a file it could not save (and why), mountable.io not answering
for 30 seconds and answering again, a failed certificate renewal, and a
revocation, expiry or error that stops the mount. Add --verbose to see
the mount engine's full log when you are debugging.
mountable unmount
mountable unmount ~/workUnmounts DIR cleanly; the mountable mount process finishes its pending
writes and exits. If DIR is busy (a file is still open), the mount is
aborted instead and writes not yet committed may be lost.
mountable mcp
Runs an MCP server over stdio; see MCP.
mountable logout
mountable logoutSigns the CLI out and deletes its stored tokens.
If an API key is still supplied through MOUNTABLE_API_KEY, later commands
continue to use that separate credential; signing out does not revoke keys.
mountable version
mountable versionPrints the CLI version:
mountable 0.8.0mountable licenses
mountable licensesPrints the licenses and notices of the third-party open-source code compiled
into the CLI. Packages and release archives also carry them as
THIRD_PARTY_NOTICES.
Output, errors and exit codes
--jsonwrites one JSON document to stdout, with the API's field names (help --jsonwrites{"usage": …};mount --jsonwrites JSON lines). Diagnostics go to stderr. Nothing ever prompts.mountable mcpis the exception: its stdout is the MCP protocol.- Exit codes:
0success;1an error from the API, network, mount or credentials;2wrong usage. - Errors carry a stable code and a next step: on stderr, or with
--jsonas{"error":{"code":…,"message":…,"hint":…}}on stdout. The codes are listed on Agents. - The one-time ticket appears only in the result of
ticket create. API and management keys, login tokens, certificates, tickets and webhook secrets never appear in errors or logs; a webhook secret is printed only bywebhooks createandwebhooks rotate-secret, and a new key's secret only byapi-keys createands3-keys create.
Retries
The CLI never retries by itself.
- Reads (
orgs list,fs list,fs get,fs usage,sessions list,files read,files list,files changes,webhooks list,api-keys list,s3-keys list,grants list) are safe to retry. So isfs update, which sets the values given. ticket createsends an idempotency key. When the outcome is unknown (network_errororoutcome_unknown), the error'sidempotency_keyis the key that request was sent with: retry with exactly that key. A replay returns the existing session without a ticket:- still
requested: its ticket was lost. The CLI revokes that session, creates a new one with a fresh key and reports both session IDs (replaced_session_id). activeor later: the ticket was used. The CLI revokes nothing and fails withticket_already_used; use a new key for another mount.
- still
fs createhas no idempotency key. After a timeout, runfs listand look for the name before creating again.sessions revoke,webhooks enable,api-keys revoke,s3-keys revokeandgrants setare idempotent. A repeatedfs deleteorgrants deleteanswersnot_found.api-keys createands3-keys createshow the secret once: after a timeout, list the keys, revoke one with that name, and create a new one.files writeandfiles deletehave an unknown outcome after a timeout: read the file (or list) first, or retry with--if-match/--if-none-match.webhooks createandrotate-secretmake a new secret each time: after a timeout, runwebhooks listbefore creating again, and after a rotation rotate again and store that secret. A repeatedwebhooks deleteanswersnot_found.- On HTTP 429 (
rate_limited), waitretry_afterseconds.
Requirements and environment
mountable mount needs FUSE (/dev/fuse and fusermount on Linux). It keeps
each mount's cache in your user cache directory (~/.cache/mountable on
Linux) and removes it when the mount ends.
| Variable | Meaning |
|---|---|
MOUNTABLE_API_KEY | an API key or a management key, used instead of the login |
MOUNTABLE_ORG | the organisation, when --org is not given |
MOUNTABLE_API_URL | the mountable.io API to use (default https://mountable.io) |