Work from the command line

Find, add, tag, link and bin your items with the marfa command, from any computer you sign in on.

With the marfa command you can do anything on your instance from any computer that reaches it, except approve an app, which you do in your browser. This page covers the commands you use day to day. The CLI reference lists every command and option.

Sign in

On each computer, sign the CLI in once, with your instance's address:

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

Your browser opens with a code filled in. Select Continue, sign in if your browser asks, choose Full access, check that the code matches the one in the terminal, and select Approve. The CLI keeps the sign-in in your keychain, so later commands need no address or key. marfa whoami shows which instance and sign-in a command uses.

On a computer with no browser, such as a server you reach over SSH, add --no-browser: the CLI prints the page to open, and you approve it on any device. A computer with no keychain uses a key instead, as the next section shows.

Use a key instead of signing in

A script, a CI job or a computer with no keychain uses a key, which Manage keys shows how to make. Put the instance's address in MARFA_API_URL and the key in MARFA_API_KEY, and set MARFA_NO_KEYCHAIN=1 so the CLI neither reads nor writes the keychain:

export MARFA_API_URL=https://marfa.example.com
export MARFA_API_KEY=marfa_k1_…
MARFA_NO_KEYCHAIN=1 marfa items list

Prefer MARFA_API_KEY to --key. Other users of the computer can read a command line, and it stays in your shell history. A key always needs its server named, with MARFA_API_URL or --url, so it's never sent to another instance by mistake.

Better still, leave the key in your password manager. With 1Password, MARFA_API_KEY holds a secret reference, and op run replaces it with the key for that one command:

export MARFA_API_URL=https://marfa.example.com
export MARFA_API_KEY="op://Private/Marfa/key"
MARFA_NO_KEYCHAIN=1 op run -- marfa items list

For a computer you use every day, a profile names the server and the command that reads its key, as Work from an agent shows.

Find items

Search across every item you can reach, of every type:

Terminal
marfa search lisbon
score    id                                    type           when                      title
  1.000  01a1f166-8cb0-7605-807f-d4c89178f4d1  core.bookmark  2026-11-19T01:23:12.176Z  Hotel in Lisbon
  0.862  01a1f167-3524-769f-bb84-884191bc60f2  core.note      2026-11-19T01:23:55.299Z  Lisbon packing list
  0.824  01a1f167-35a4-75ea-8947-c51cf3a5bf4e  core.file      2026-11-19T01:23:55.427Z  Lisbon hotel booking
  0.654  01a1f165-1eab-700e-b1f9-8113132d108d  core.note      2026-11-19T01:21:43.258Z  Packing
  • marfa search lisbon --type core.file finds only files, here the hotel booking.
  • marfa items list --tag lisbon lists every item that carries a tag, newest first.
  • marfa items list --tier feed lists what connectors brought in.
  • marfa items get <id> shows one item, with its version and properties.
  • marfa tags lists every tag in use, with how many items carry it.

Add items

marfa items add saves a file from your computer. Marfa picks the type from the file, so a photo becomes a core.file.image:

marfa items add ~/Pictures/beach.png --title "Beach at Comporta" --tag travel

marfa items create makes any other item, with its type and properties:

Terminal
marfa items create --type core.note --prop title="Lisbon packing list" \
  --prop body="Sun hat, adapter" --tag lisbon
marfa: writing to https://marfa.example.com
created core.note 01a1f167-3524-769f-bb84-884191bc60f2 "Lisbon packing list" (version 1)

The Catalog lists each type's properties.

Change an item

A change names the version you read, so it never quietly overwrites an edit made since, from your editor or an agent. Read the item, then send its version:

Terminal
marfa items update 01a1f167-3524-769f-bb84-884191bc60f2 --version 1 \
  --prop body="Sun hat, adapter, sandals"
marfa: writing to https://marfa.example.com
updated core.note 01a1f167-3524-769f-bb84-884191bc60f2 "Lisbon packing list" (version 2)

If the item changed after you read it, the server compares the two changes. When they touch different properties, such as your new body and someone else's new title, it writes both and answers with the new version. When both change the same property, nothing is written, and the command names the property:

marfa: writing to https://marfa.example.com
marfa: the server refused (409 version_conflict): Version 1 is stale; current version is 2. Conflicting fields: body.

Read the item again with marfa items get, and send your change with the new version.

To keep an item that a connector brought into the feed, move it to the library: marfa items update <id> --version <n> --tier library.

  • marfa items tags add <id> packing puts one or more tags on an item.
  • marfa items tags remove <id> packing takes one off.
  • marfa items tags replace <id> lisbon travel sets the item's tags whole.

An edge links two items, and says how. This one says the note references the bookmark:

Terminal
marfa edges create --from-id 01a1f167-3524-769f-bb84-884191bc60f2 \
  --to-id 01a1f166-8cb0-7605-807f-d4c89178f4d1 --type references
marfa: writing to https://marfa.example.com
linked 01a1f167-3524-769f-bb84-884191bc60f2 -> 01a1f166-8cb0-7605-807f-d4c89178f4d1 with references edge 01a1f167-4c38-7005-97d0-bba131c848d1

marfa items edges <id> lists the edges leaving an item, and marfa items backrefs <id> the edges arriving at it. marfa edge-types list lists every kind of edge.

Move items to the bin

marfa items trash moves up to 20 items to the bin, all of them or none. Each takes the items beneath it, such as a task's subtasks. First see what would move, then send the digest it gives you, so nothing moves if that has changed:

Terminal
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 --dry-run
items[0].id       01a1f167-3524-769f-bb84-884191bc60f2
items[0].type     core.note
items[0].version  2
items[0].takes    (none)
items[0].count    1
items[1].id       01a1f166-8cb0-7605-807f-d4c89178f4d1
items[1].type     core.bookmark
items[1].version  1
items[1].takes    (none)
items[1].count    1
count             2
digest            7b15a139713b9bdad3a46cf213ba6abab1e9a4f0abce34c0e79b7d332a7602db

Nothing has moved yet. When the list is right, run it again with the digest:

Terminal
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 \
  --digest 7b15a139713b9bdad3a46cf213ba6abab1e9a4f0abce34c0e79b7d332a7602db
marfa: writing to https://marfa.example.com
moved 01a1f167-3524-769f-bb84-884191bc60f2, 01a1f166-8cb0-7605-807f-d4c89178f4d1 to the bin

marfa items bin list shows what's in the bin and when each item can be deleted for good. marfa items restore <id> brings one back as it was.

Use the output in a script

Add --json to any command for an answer a script or an agent can read. A refusal is then one JSON object on the last line of standard error, and the exit code says what kind of failure it was, as the CLI reference lists.

marfa --json items get 01a1f166-8cb0-7605-807f-d4c89178f4d1

When a command reaches the wrong instance

Start with marfa whoami. It 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 01a1f19a-898f-70db-96aa-46664155c6bb (Marfa 0.0.80)
a key named laptop from MARFA_API_KEY

If the server or the credential isn't the one you meant, Connect to a server gives the order the CLI looks for each, and Fix a command that can't find its server or key explains each message.

On this page