CLI reference

Install

npx -y mountable-cli login                          # npm
uvx mountable login                                 # PyPI
curl -fsSL https://mountable.io/install.sh | sh     # installs to ~/.local/bin

Every channel installs the same mountable binary, for Linux and macOS on x86_64 and arm64. Mounting is verified on Linux x86_64 only; see Contract and limits. The binary is self-contained: mounting downloads nothing else, and the session's key and certificate stay in memory. The install script checks the package against the npm registry's sha512 checksum; set MOUNTABLE_VERSION to install a specific version and MOUNTABLE_INSTALL_DIR to install elsewhere. It never uses sudo.

Commands

mountable login
mountable logout
mountable orgs list
mountable fs list [--org ORG_ID]
mountable fs create NAME [--org ORG_ID]
mountable fs usage FS_ID [--org ORG_ID]
mountable ticket create FS_ID [--ro] [--idempotency-key KEY]
mountable sessions list FS_ID [--org ORG_ID]
mountable sessions revoke SESSION_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. Deleting a filesystem is done in the console.

Authentication and organisation

• People: mountable login signs this machine in.
• Backends and agents: set MOUNTABLE_API_KEY=mtbl_…. It is used instead of the login. An API key belongs to one organisation, and the commands use it.
• 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.

mountable orgs list

Lists the caller's organisations. An API key has exactly one.

mountable fs

mountable fs list
FS_ID=$(mountable fs create agent-workspace)
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. A filesystem created with an API key gets a read-write grant for that key.
• fs usage FS_ID shows stored bytes and files against the quotas, and the traffic over 30 days.

mountable ticket create

mountable ticket create "$FS_ID" --idempotency-key job-42
mountable ticket create "$FS_ID" --ro --idempotency-key job-43 --json

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.

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 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.

When the session is revoked or expires, the CLI aborts the mount at once: 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.

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.

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.

mountable version

mountable version

Prints the CLI version:

mountable 0.3.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 keys, login tokens, certificates and tickets never appear in errors or logs.

Retries

• Reads (orgs list, fs list, fs usage, sessions list) are safe to retry.
• 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 is idempotent.
• 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.