CLI
Install the marfa program, see how it finds your instance and credential, and look up its options and exit codes.
The CLI is the marfa program. Every operation in the API has a command, such as marfa items list, except Authorize an app, which an app opens in a person's browser: marfa login signs in with a device code instead. Work from the command line shows the everyday commands. The CLI also does work the API doesn't:
marfa serverinstalls, upgrades and removes a server on this machine, as Install on a Mac or Linux machine shows.marfa folderskeeps part of an instance as files in a directory, as Sync a folder shows.marfa folders revokeretires a folder on the instance for good.marfa devicekeeps a working copy of part of an instance, as Write in a working copy shows.marfa types scaffoldprints a starting definition for a type without a server, as Define a type shows.marfa docssearches these docs from the terminal, as Docs MCP server shows.
marfa <command> --help is the reference for each command: what it does and every option it takes, for the version you have. This page covers what every command shares.
Install
Install with the install script, on macOS with Apple silicon or on Linux, x86_64 or arm64. It picks the archive for your machine, checks it against the release's checksum file, and puts marfa and marfa-server side by side in ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/withmarfa/marfa/main/scripts/install.sh | sh
marfa --version- When that folder isn't on your
PATH, the script prints theexport PATH=line to add to your shell's startup file. Until you add it and open a new shell,marfaisn't found. MARFA_VERSIONinstalls a release other than the latest, andMARFA_INSTALL_DIRinstalls somewhere else.- Intel Macs aren't supported.
Homebrew installs the same two programs with brew install withmarfa/tap/marfa. marfa server install then sets up a server on the same machine, running the marfa-server installed beside marfa.
Update the CLI
On a computer that runs no server, run the install script again, which installs the latest release over the last, or run brew upgrade marfa.
On the server's own machine, leave the server's programs as they are. The server runs the marfa-server beside the marfa that installed it, so replacing them moves the server to the new release the next time it starts, which Upgrade an instance advises against before Marfa 0.1. Install the newer CLI into a folder of its own, and run it by its path:
curl -fsSL https://raw.githubusercontent.com/withmarfa/marfa/main/scripts/install.sh | MARFA_INSTALL_DIR=~/marfa-cli sh
~/marfa-cli/marfa statusLeave that folder off your PATH, whatever the script suggests, so marfa stays the server's own and every marfa server command runs the server's release.
Download an archive yourself
Each release carries three archives, marfa-<version>-darwin-arm64.tar.gz, -linux-x86_64.tar.gz and -linux-aarch64.tar.gz, and a checksum file, marfa-<version>-checksums.txt. Each archive holds marfa, marfa-server and NOTICES.txt. On a Mac:
curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.86/marfa-0.0.86-darwin-arm64.tar.gz | tar -xz
sudo mkdir -p /usr/local/bin
sudo mv marfa marfa-server /usr/local/bin/
marfa --versionThe checksum file shows that a download is intact. To check that the release workflow of withmarfa/marfa built it, verify its build attestation with the GitHub CLI, in the folder that holds the archive:
gh attestation verify marfa-<version>-linux-x86_64.tar.gz \
--repo withmarfa/marfa \
--signer-workflow withmarfa/marfa/.github/workflows/release.yml \
--source-ref refs/tags/v<version>It fails if the file has no attestation from that workflow at that tag. Verify the checksum file the same way. The macOS programs are also signed with a Developer ID and notarized by Apple.
Connect to a server
A command that talks to an instance needs the server's address and a credential. The CLI takes both from the first of these that is given:
--profile: a profile, which holds a server and where its key comes from. It's refused beside--urlor--key, and it reads none ofMARFA_API_URL,MARFA_API_KEYandMARFA_PROFILE.--urlor--key, with noMARFA_PROFILEread beside either.MARFA_PROFILE: a profile for a whole shell. It's refused beside aMARFA_API_URLorMARFA_API_KEYthat isn't empty, so a key exported for one server never reaches another.- No profile: the variables, then the keychain:
| What it needs | First | Then | Then |
|---|---|---|---|
| A server | --url | MARFA_API_URL, when it isn't empty | The current server: the one you last signed in to or kept a key for |
| A credential | --key | MARFA_API_KEY | What the keychain holds for that server |
A key from --key or MARFA_API_KEY needs its server named with --url or MARFA_API_URL, so it's never sent to the current server by mistake. A --url for another server than MARFA_API_URL doesn't use MARFA_API_KEY.
A key or token sent over plain http to a host other than this machine gets a warning on standard error, and is sent anyway. On a private network, --allow-http or MARFA_ALLOW_HTTP=1 says you mean it and drops the warning.
Name a server with a profile
A profile is a section of a file you write by hand, profiles.toml, that names a server and where its key comes from (profile rules). It isn't the owner's profile, which marfa profile changes. A profile's key goes only to its own server. The file is ~/Library/Application Support/Marfa/profiles.toml on macOS, and $XDG_CONFIG_HOME/marfa/profiles.toml, or ~/.config/marfa/profiles.toml where that isn't set, elsewhere:
[demo]
url = "http://localhost:8600"
[example]
url = "https://marfa.example.com"
key_command = ["op", "read", "op://Private/Marfa/key"]Pick one for a command with --profile, or for a whole shell with MARFA_PROFILE:
marfa --profile example items list
export MARFA_PROFILE=demo- Without
key_command, the key is the keychain's credential for that server.marfa login --profile demosigns in to it, andmarfa keys keep --profile demokeeps a key for it, read from standard input. - With
key_command, the CLI runs it and reads the key from what it prints. It's a program and its arguments, run without a shell and with no standard input, when a request first needs the key and at most once in a run. It must print the key alone on one line, finish within 60 seconds and exit with 0. It can't use the terminal, so a program that asks for a password must ask in a window of its own.loginwithout--print-token,logout,keys keepandkeys forgetrefuse such a profile. - The CLI refuses a file that others can change: one that belongs to another user, or that its group or others can write, or whose folder they can write. The refusal names the
chmodorchownthat fixes it. It refuses a field it doesn't know too, so a misspelledkey_commandcan't leave a profile on the keychain unseen. --socket,marfa serverandmarfa types scaffoldrefuse--profile, since none of them uses a server's address and key.
Keep a credential in the keychain
The keychain holds one credential for each server, and only what these commands put there:
| Command | What it does |
|---|---|
marfa login | Signs in as an app with the device flow: you approve what it may reach on a page on the server, and it keeps the app's token. It refuses while a key is kept for that server. |
marfa logout | Revokes the token and forgets it. |
marfa keys keep | Checks a key you already have with the server, then keeps it. |
marfa keys forget | Forgets a kept key, without revoking it. |
marfa login --url https://marfa.example.comManage keys shows how to make a key to keep. A keychain that is locked, missing or unreadable ends a command with exit code 4, no_keychain.
Run without the keychain
For a script, a CI job or an agent, pass --no-keychain or set MARFA_NO_KEYCHAIN=1. The CLI then reads nothing from the keychain and writes nothing to it, so it can't raise a system prompt, and a command that names no server is refused instead of reaching the current one. Every command needs a profile with a key_command, or --url or MARFA_API_URL with the credential from --key or MARFA_API_KEY.
marfa keys keep, keys forget and login without --print-token refuse. marfa login --print-token prints the token set instead of keeping it, and marfa logout revokes the token passed with --key or MARFA_API_KEY.
Use another keychain file
On macOS, MARFA_KEYCHAIN names a keychain file to use instead of your own, for a run with nobody there to answer a prompt. The file must already exist: marfa login, logout, keys keep and keys forget refuse a missing one with exit code 4, and other commands find nothing kept in it. Make one with security create-keychain -p '' <path>. On other systems the CLI refuses the variable.
marfa folders watch with no directory, and the login agent that marfa folders autostart on sets up, read each folder's credential from the keychain. For a machine where nobody signs in to unlock it, give them a key file instead, as Give a key to a folder watch shows.
Use the private socket
On the instance's own machine, as the account that runs the server, --socket <path> acts with the machine's own authority instead of a credential, through the private socket. Every owner task works through it, such as marfa setup status, marfa keys list, marfa sign-ins list and marfa config get, and claiming the instance and recovering the owner's password need it.
- The socket carries no key, so item properties, edges, tags, search, counts, events, exports and
marfa overvieware refused401 unauthorized, and the CLI exits with 5.items summaries,items bin,items trash,items restoreanditems purgeof one item, theblobscommands, anditems bulk-action jobandcancelwork through it. - It can't be combined with a profile, a server or a key, from an option or the environment, so unset
MARFA_API_URL,MARFA_API_KEYandMARFA_PROFILEfirst. - Commands that use no server or keep a credential refuse it, such as
login,server,device,docs,types scaffoldand everyfolderscommand exceptfolders inventory.
Check which server a write reaches
Before a command first sends a request that can change data, the CLI prints marfa: writing to <server> on standard error as one plain line, with (profile <name>) after it where a profile named the server. Through the socket, the server is unix:<path>. A read prints nothing, and neither does signing in. The line is printed with --json too, and standard output is unchanged:
marfa items create --type core.bookmark --prop title="Field guide" --prop url=https://example.com/guidemarfa: writing to https://marfa.example.comSee which server and credential a command uses
marfa whoami asks the server a command would reach, and prints the server, the instance with its name and release, and the credential and where it came from:
marfa whoamiserver https://marfa.example.com
instance 01a1f11d-c2f1-7630-9670-c83bbe952280 (Marfa 0.0.80)
a key named laptop from MARFA_API_KEYWith a profile, the first line ends with (profile example). Under an app's token, whoami also lists what the owner approved, in the words of the approval page. marfa keys list and keys current print a key's access the same way, and --json prints it structured. marfa overview shows what the credential can reach: types with item counts, edge types, top tags, views and folders. It needs no type access.
Output
--jsonprints the answer as JSON. Every list prints{"data": [...], "next_cursor": ...}, and a command for a paged operation takes--limit,--cursorand--all.- A refusal under
--jsonis the last line of standard error, one JSON object witherrorandexit, after any plain lines such as a warning or the write line. - Bold and color are for a person only. A stream that isn't a terminal, a
NO_COLORthat isn't empty, aTERMofdumbor--jsongets no escape characters. Each stream is judged alone, and color never says what the words don't. marfa operationslists each operation in the API reference beside the command that reaches it, without sending a request.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done. |
| 1 | The server refused the request (a wrong or spent setup code included), the CLI refused it before sending, the answer came from another contract, a docs page does not exist, or the archive of an export or a restore lacks blobs it names; a retry does not change it. |
| 2 | The command line or the profile file was wrong, or named no store or server. |
| 3 | The environment failed (unreachable, timed out, a 5xx, a 408, a 425, a 429, an answer naming no contract, full local storage, a working copy another program was writing to, a docs site that cannot be read, a new build installed under folders watch --exit-on-new-build, a sign-in code that is no longer valid); try again. |
| 4 | The working copy or the queue refused under the device rules, the keychain cannot be used (locked, missing, unreadable, or none on this system), or the core stopped on a fault of its own. |
| 5 | There is no credential, a profile's key command gave none, the credential was refused, or the sign-in ended; run marfa login to start one. |
| 130 | You ended a long-lived command (folders watch, events, device changes) with Ctrl-C, or ended one that was still stopping with a second Ctrl-C. |
marfa device drain prints its complete report on stdout and sets the exit code from it: 0 when the pass completed (refused writes included), 3 when writes went undelivered or the pass could not run, and 5 when a credential stopped the pass. These exits print no additional refusal on stderr. The report counts refused verdicts separately, in plain text.
When marfa device catch-up fails, the refusal says whether the catch-up had already changed the catalog the copy holds; the copy keeps that change. With --json, the refusal carries this as "catalog_changed" beside "exit".
When the server refuses a command, the refusal ends with the server's X-Request-ID on a line of its own, Request ID: <id>; quote it when you report the problem. With --json the refusal carries it as "server.request_id". A failure the command line met without a server's answer shows none.
With --json a refusal is the last line of stderr, one JSON object, after any plain lines such as a warning or the write line:
{"error":{"code":...,"message":...,"server":{"status":...,"code":...,"details":...,"request_id":...}|null,"local":{"code":...,"details":...}|null,"retry_after_seconds":...},"exit":N}where error.code is one of: not_found, unauthorized, forbidden, validation, unknown_type, rate_limited, server, io, network, unnamed_answer, decoding, store, store_busy, storage_full, signed_out, no_keychain, redirect, no_server, no_cursor, hydration_incomplete, no_catalog, reading_handle, wrong_schema, store_damaged, unsent_differs, copy_expired, stream_incomplete, wrong_server, bytes_absent, no_room, contract_mismatch, server_too_old, canceled, first_sync_waiting, renewal_refused, invalid, not_answerable, fault, watch, usage, install, no_store, no_credential, key_command, device_code_ended, blobs_missing, docs_page_not_found, docs_section_not_found, docs_unreachable, conflict, too_large.
Global options
Every command accepts these.
| Option | Description |
|---|---|
--profile <NAME> | A profile in profiles.toml: a server, and where its key comes from. Not the owner's profile, which marfa profile changes. The file is ~/Library/Application Support/Marfa/profiles.toml on macOS, and $XDG_CONFIG_HOME/marfa/profiles.toml, else ~/.config/marfa/profiles.toml, elsewhere. Each profile is a section with a url line and, optionally, key_command: a program and its arguments, run without a shell, that prints the key. Without key_command, the key is the credential the keychain keeps for that server. The server and key come from the first of these that is given: --profile, which refuses --url and --key beside it and reads none of MARFA_API_URL, MARFA_API_KEY and MARFA_PROFILE; --url or --key, as below, without MARFA_PROFILE; MARFA_PROFILE, which refuses MARFA_API_URL and MARFA_API_KEY beside it; MARFA_API_URL and MARFA_API_KEY, then the keychain. A profile's key is sent only to its server, and no other key is. |
--url <URL> | The server's base URL. Falls back to MARFA_API_URL, then to the server a kept credential made current. MARFA_PROFILE is not read beside it. A command that sends a key from --key or MARFA_API_KEY needs the URL named, and so does any command with the keychain off. With MARFA_API_KEY set, a different server from MARFA_API_URL requires --key. |
--key <KEY> | A key or a token for that server. Prefer MARFA_API_KEY or the keychain: a command line is readable by other users of the machine and stays in shell history. Falls back to MARFA_API_KEY, which a --url for another server than MARFA_API_URL names does not use, then to the keychain: the file MARFA_KEYCHAIN names, where it names one, unless the keychain is off. MARFA_PROFILE is not read beside it. |
--no-keychain | Treat the keychain as absent: read nothing from it and write nothing to it, so the server and the key must come from --url, --key, MARFA_API_URL or MARFA_API_KEY, or a profile with a key_command. A command that needs to keep something refuses. MARFA_NO_KEYCHAIN=1 does the same. |
--allow-http | Send a credential over plain http to a host that is not this machine without the warning, for a network that is private. MARFA_ALLOW_HTTP=1 does the same. |
--socket <PATH> | Use private local process authority through this Unix socket, without a keychain. Item properties, edges, tags, search, counts, events and exports still need a key. items summaries, items bin, items trash, items restore and items purge of one item, the blobs commands and bulk-action job status and cancel do not. |
--json | Print the answer as JSON. A refusal is the last line of stderr, one JSON object, after any plain lines such as a warning or the write line. |
marfa itself also accepts these.
| Option | Description |
|---|---|
-V, --version | Print version. |