# Work from the command line (/use/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/cli) reference lists every command and option.

## Sign in [#sign-in]

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

```bash
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 [#use-a-key-instead-of-signing-in]

A script, a CI job or a computer with no keychain uses a key, which [Manage keys](/run/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:

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

```bash
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](/reference/cli#name-a-server-with-a-profile) names the server and the command that reads its key, as [Work from an agent](/use/from-an-agent#an-agent-that-runs-commands) shows.

## Find items [#find-items]

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

```bash
marfa search lisbon
```

Output:

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

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

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

```bash
marfa items create --type core.note --prop title="Lisbon packing list" \
  --prop body="Sun hat, adapter" --tag lisbon
```

Output:

```text
marfa: writing to https://marfa.example.com
created core.note 01a1f167-3524-769f-bb84-884191bc60f2 "Lisbon packing list" (version 1)
```

The [Catalog](/catalog/types) lists each type's properties.

## Change an item [#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:

```bash
marfa items update 01a1f167-3524-769f-bb84-884191bc60f2 --version 1 \
  --prop body="Sun hat, adapter, sandals"
```

Output:

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

```text
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 [#tag-and-link-items]

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

```bash
marfa edges create --from-id 01a1f167-3524-769f-bb84-884191bc60f2 \
  --to-id 01a1f166-8cb0-7605-807f-d4c89178f4d1 --type references
```

Output:

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

```bash
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 --dry-run
```

Output:

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

```bash
marfa items trash 01a1f167-3524-769f-bb84-884191bc60f2 01a1f166-8cb0-7605-807f-d4c89178f4d1 \
  --digest 7b15a139713b9bdad3a46cf213ba6abab1e9a4f0abce34c0e79b7d332a7602db
```

Output:

```text
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 [#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/cli) reference lists.

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

## When a command reaches the wrong instance [#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:

```bash
marfa whoami
```

Output:

```text
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](/reference/cli#connect-to-a-server) gives the order the CLI looks for each, and [Fix a command that can't find its server or key](/run/troubleshooting/cli) explains each message.
