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 <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 the export PATH= line to add to your shell's startup file. Until you add it and open a new shell, marfa isn't found.
  • MARFA_VERSION installs a release other than the latest, and MARFA_INSTALL_DIR installs 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 status

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

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

  1. --profile: a profile, which holds a server and where its key comes from. It's refused beside --url or --key, and it reads none of MARFA_API_URL, MARFA_API_KEY and MARFA_PROFILE.
  2. --url or --key, with no MARFA_PROFILE read beside either.
  3. MARFA_PROFILE: a profile for a whole shell. It's refused beside a MARFA_API_URL or MARFA_API_KEY that isn't empty, so a key exported for one server never reaches another.
  4. No profile: the variables, then the keychain:
What it needsFirstThenThen
A server--urlMARFA_API_URL, when it isn't emptyThe current server: the one you last signed in to or kept a key for
A credential--keyMARFA_API_KEYWhat 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:

profiles.toml
[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 demo signs in to it, and marfa keys keep --profile demo keeps 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. login without --print-token, logout, keys keep and keys forget refuse 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 chmod or chown that fixes it. It refuses a field it doesn't know too, so a misspelled key_command can't leave a profile on the keychain unseen.
  • --socket, marfa server and marfa types scaffold refuse --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:

CommandWhat it does
marfa loginSigns 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 logoutRevokes the token and forgets it.
marfa keys keepChecks a key you already have with the server, then keeps it.
marfa keys forgetForgets a kept key, without revoking it.
marfa login --url https://marfa.example.com

Manage 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 overview are refused 401 unauthorized, and the CLI exits with 5. items summaries, items bin, items trash, items restore and items purge of one item, the blobs commands, and items bulk-action job and cancel work 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_KEY and MARFA_PROFILE first.
  • Commands that use no server or keep a credential refuse it, such as login, server, device, docs, types scaffold and every folders command except folders 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:

Terminal
marfa items create --type core.bookmark --prop title="Field guide" --prop url=https://example.com/guide
marfa: writing to https://marfa.example.com

See 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:

Terminal
marfa whoami
server https://marfa.example.com
instance 01a1f11d-c2f1-7630-9670-c83bbe952280 (Marfa 0.0.80)
a key named laptop from MARFA_API_KEY

With 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

  • --json prints the answer as JSON. Every list prints {"data": [...], "next_cursor": ...}, and a command for a paged operation takes --limit, --cursor and --all.
  • A refusal under --json is the last line of standard error, one JSON object with error and exit, 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_COLOR that isn't empty, a TERM of dumb or --json gets no escape characters. Each stream is judged alone, and color never says what the words don't.
  • marfa operations lists each operation in the API reference beside the command that reaches it, without sending a request.

Exit codes

CodeMeaning
0Done.
1The 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.
2The command line or the profile file was wrong, or named no store or server.
3The 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.
4The 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.
5There 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.
130You 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.

OptionDescription
--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-keychainTreat 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-httpSend 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.
--jsonPrint 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.

OptionDescription
-V, --versionPrint version.

On this page