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.comYour 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 listPrefer 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 listFor 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:
marfa search lisbonscore 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 Packingmarfa search lisbon --type core.filefinds only files, here the hotel booking.marfa items list --tag lisbonlists every item that carries a tag, newest first.marfa items list --tier feedlists what connectors brought in.marfa items get <id>shows one item, with its version and properties.marfa tagslists 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 travelmarfa items create makes any other item, with its type and properties:
marfa items create --type core.note --prop title="Lisbon packing list" \
--prop body="Sun hat, adapter" --tag lisbonmarfa: 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:
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.
Tag and link items
marfa items tags add <id> packingputs one or more tags on an item.marfa items tags remove <id> packingtakes one off.marfa items tags replace <id> lisbon travelsets the item's tags whole.
An edge links two items, and says how. This one says the note references the bookmark:
marfa edges create --from-id 01a1f167-3524-769f-bb84-884191bc60f2 \
--to-id 01a1f166-8cb0-7605-807f-d4c89178f4d1 --type referencesmarfa: writing to https://marfa.example.com
linked 01a1f167-3524-769f-bb84-884191bc60f2 -> 01a1f166-8cb0-7605-807f-d4c89178f4d1 with references edge 01a1f167-4c38-7005-97d0-bba131c848d1marfa 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:
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 --dry-runitems[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 7b15a139713b9bdad3a46cf213ba6abab1e9a4f0abce34c0e79b7d332a7602dbNothing has moved yet. When the list is right, run it again with the digest:
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 \
--digest 7b15a139713b9bdad3a46cf213ba6abab1e9a4f0abce34c0e79b7d332a7602dbmarfa: writing to https://marfa.example.com
moved 01a1f167-3524-769f-bb84-884191bc60f2, 01a1f166-8cb0-7605-807f-d4c89178f4d1 to the binmarfa 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-d4c89178f4d1When 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:
marfa whoamiserver https://marfa.example.com
instance 01a1f19a-898f-70db-96aa-46664155c6bb (Marfa 0.0.80)
a key named laptop from MARFA_API_KEYIf 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.