# CLI (/reference/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](/reference/api/apps/authorizeApp), which an app opens in a person's browser: `marfa login` signs in with a device code instead. [Work from the command line](/use/command-line) shows the everyday commands. The CLI also does work the API doesn't:

* `marfa server` installs, upgrades and removes a server on this machine, as [Install on a Mac or Linux machine](/run/install) shows.
* `marfa folders` keeps part of an instance as files in a directory, as [Sync a folder](/use/sync-a-folder) shows. `marfa folders revoke` retires a folder on the instance for good.
* `marfa device` keeps a [working copy](/build/devices) of part of an instance, as [Write in a working copy](/build/write-in-a-working-copy) shows.
* `marfa types scaffold` prints a starting definition for a type without a server, as [Define a type](/build/define-a-type) shows.
* `marfa docs` searches these docs from the terminal, as [Docs MCP server](/reference/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]

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

```bash
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`](/run/install) then sets up a server on the same machine, running the `marfa-server` installed beside `marfa`.

### Update the CLI [#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](/run/upgrade) advises against before Marfa 0.1. Install the newer CLI into a folder of its own, and run it by its path:

```bash
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 [#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:

```bash
curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.87/marfa-0.0.87-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](https://cli.github.com), in the folder that holds the archive:

```bash
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 [#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](#name-a-server-with-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 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 [#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](https://github.com/withmarfa/marfa/blob/main/conformance/spec/cli.md#profiles)). 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:

```toml title="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`:

```bash
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 [#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](/build/authenticate#connect-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. |

```bash
marfa login --url https://marfa.example.com
```

[Manage keys](/run/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 [#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 [#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](/run/manage-keys#give-a-key-to-a-folder-watch) shows.

### Use the private socket [#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](/run/run-on-a-server#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 [#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:

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

Output:

```text
marfa: writing to https://marfa.example.com
```

## See which server and credential a command uses [#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:

```bash
marfa whoami
```

Output:

```text
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 [#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](/reference/api) beside the command that reaches it, without sending a request.

## Exit codes [#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:

```text
{"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`, `sync_paused`, `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 [#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. |
