mountable.io

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 PyPI

The 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 licenses

Every 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 login signs 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, the files commands 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_required or api_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 login

Signs 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 list lists filesystems. An API key sees only those it has a grant on.
  • fs create NAME creates 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 with grants set, or create a key for it with api-keys create --filesystem.
  • fs get FS_ID shows the filesystem and its four limits.
  • fs update FS_ID changes only the limits given and prints the result like fs get; none removes the spending cap or the custom rate. It needs at least one flag.
  • fs usage FS_ID shows stored bytes and files against the quotas, the traffic over 30 days, and with --json this month's reserved_cents.
  • fs delete FS_ID deletes 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 720h

Creates 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 write sends --from FILE, or stdin, as the whole file and prints its path, ETag and size (--json: its FileInfo). --if-match ETAG writes only if the file still has that ETag; --if-none-match only if nothing exists at the path. A failed condition is precondition_failed, whose error holds the file's current_etag.
  • files read writes the file's bytes to stdout, or to --to FILE, which is replaced only once the whole file arrived (with mode 0600). --json needs --to and prints the FileInfo. A read to stdout that breaks off exits with 1, and the bytes already written are incomplete.
  • files list prints one directory page: type, size, modified time and path. When there are more entries, stderr says which --after to pass.
  • files changes without --cursor prints the current cursor at once; with it, it waits up to --wait seconds (default 25) for the changes after it. Events are TYPE PATH lines; the next cursor goes to stderr. See following changes.
  • files delete deletes 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 ~/work

Creates 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/work

Mounts 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 ~/work

Unmounts 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 logout

Signs 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 version

Prints the CLI version:

mountable 0.8.0

mountable licenses

mountable licenses

Prints 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

  • --json writes one JSON document to stdout, with the API's field names (help --json writes {"usage": …}; mount --json writes JSON lines). Diagnostics go to stderr. Nothing ever prompts. mountable mcp is the exception: its stdout is the MCP protocol.
  • Exit codes: 0 success; 1 an error from the API, network, mount or credentials; 2 wrong usage.
  • Errors carry a stable code and a next step: on stderr, or with --json as {"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 by webhooks create and webhooks rotate-secret, and a new key's secret only by api-keys create and s3-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 is fs update, which sets the values given.
  • ticket create sends an idempotency key. When the outcome is unknown (network_error or outcome_unknown), the error's idempotency_key is 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).
    • active or later: the ticket was used. The CLI revokes nothing and fails with ticket_already_used; use a new key for another mount.
  • fs create has no idempotency key. After a timeout, run fs list and look for the name before creating again.
  • sessions revoke, webhooks enable, api-keys revoke, s3-keys revoke and grants set are idempotent. A repeated fs delete or grants delete answers not_found.
  • api-keys create and s3-keys create show the secret once: after a timeout, list the keys, revoke one with that name, and create a new one.
  • files write and files delete have an unknown outcome after a timeout: read the file (or list) first, or retry with --if-match / --if-none-match.
  • webhooks create and rotate-secret make a new secret each time: after a timeout, run webhooks list before creating again, and after a rotation rotate again and store that secret. A repeated webhooks delete answers not_found.
  • On HTTP 429 (rate_limited), wait retry_after seconds.

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.

VariableMeaning
MOUNTABLE_API_KEYan API key or a management key, used instead of the login
MOUNTABLE_ORGthe organisation, when --org is not given
MOUNTABLE_API_URLthe mountable.io API to use (default https://mountable.io)