# Command line tool

> Search, read and add to your library from Terminal or a script with the resurf command.

- Page: https://resurf.so/guides/command-line
- Section: Agents
- Works on: Mac
- Last checked against the app: 2026-10-17
- Install: Settings → MCP → Advanced
- Command: resurf

## Install it

1. Open **Settings → MCP** and expand **Advanced**.
2. On **Terminal command**, click **Copy**.
3. Paste it in Terminal and press `Return`.
4. If it says `~/.local/bin` isn't on your PATH, add the line it prints to your shell file. If it says your shell still runs a different `resurf`, remove that one as it tells you.
5. Open a new Terminal window and run `resurf --version`.

## Common commands

- `resurf find "words"` searches and filters your captures. Start here.
- `resurf note --title "…" --body "…"` saves a note.
- `resurf link <url>` saves a link.
- `resurf file <path>` saves a file.
- `resurf open <id>` opens a capture in Resurf.
- `resurf read <link>` prints a `resurf://` link as Markdown.

Add `--json` for output a script can read.

## What it doesn't do

The [Access switches](https://resurf.so/guides/agent-access) in **Settings → MCP** don't apply to it. Anything that can run `resurf` can add, organize and comment whatever the switches say.

It can't move captures to the Trash, edit a note's text, edit or delete comments, or export your library.

## Questions

### resurf says command not found.

Copy the Terminal command from Settings → MCP → Advanced and run it, then add ~/.local/bin to your PATH as it tells you. Open a new Terminal window afterwards.

### An old resurf still runs.

Run the Terminal command again. It names the old resurf and the command that removes it, such as npm uninstall -g resurf.

### Can I export my library with it?

No. The command line tool has no export command.

## More guides

- Previous: [Send captures to an agent](https://resurf.so/guides/send-to-agent.md)
- Next: [Resurf links](https://resurf.so/guides/url-scheme.md)
- [Connect an agent](https://resurf.so/guides/connect-agents.md): Add Resurf to Claude, Cursor, Codex or another MCP client once, and it can search and read your captures.
- [What agents may do](https://resurf.so/guides/agent-access.md): A connected agent can always read your library, and three switches, off by default, decide what it may change.
- [Send captures to an agent](https://resurf.so/guides/send-to-agent.md): Open Claude, Codex, Cursor or another agent with a draft that carries your captures, then send it yourself.
- [Resurf links](https://resurf.so/guides/url-scheme.md): Open a capture or a screen, or save something, from any app with a resurf:// link.
- [Every guide](https://resurf.so/llms.txt)