Command Line

MCP Setup

Connect Refbox to an MCP client such as Claude Desktop or Cursor.

Refbox can expose its CLI operations as local Model Context Protocol (MCP) tools. Use MCP when an agent can connect to an MCP server but cannot run shell commands. If the agent has terminal access, use the CLI for clearer errors and direct JSON output.

Requirements

Refbox must be running.
Turn on Settings > Data > Access Control > Command Line Access.
Restart open terminals after you enable access for the first time.

The MCP server uses standard input and output. It discovers the running Refbox app locally. You do not need to choose a port, and the port can change each time Refbox starts.

Claude Desktop

Add this block to claude_desktop_config.json, then restart Claude Desktop.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "refbox": {
      "command": "refbox",
      "args": ["mcp"]
    }
  }
}

If the client cannot find refbox, run which refbox on macOS or where refbox on Windows. Replace "refbox" in the configuration with the full path that command returns.

Cursor

Use the same mcpServers block in one of these files:

Project only: .cursor/mcp.json in the project.
All projects: ~/.cursor/mcp.json.

Restart Cursor after you save the file.

Read-Only Access

The default local connection can read and change Refbox data. To limit an MCP client to reading, create a read-only token yourself:

refbox token issue --read-only

The token is shown once. Put it in the MCP configuration:

{
  "mcpServers": {
    "refbox": {
      "command": "refbox",
      "args": ["mcp"],
      "env": {
        "REFBOX_TOKEN": "paste-the-token-here"
      }
    }
  }
}

A read-only token cannot create, update, move, delete, or restore data. If an agent reports that its token is read-only, change its permissions only if you intend to give it write access.

Available Tools

`status`

Whether Refbox is running, its version, how many boxes exist, and which one is open.

CLI equivalent: refbox status

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox status

{
  "running": true,
  "appVersion": "1.3.7",
  "protocol": 1,
  "pid": 4821,
  "scope": "readwrite",
  "boxCount": 3,
  "currentBox": {
    "id": 3,
    "name": "Album art",
    "icon": "💿",
    "itemCount": 24
  }
}

`box_list`

Every box: id, name, and item count.

CLI equivalent: refbox box list

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox box list

[
  {
    "id": 3,
    "name": "Album art",
    "icon": "💿",
    "itemCount": 24
  },
  {
    "id": 5,
    "name": "Brand references",
    "icon": "🎨",
    "itemCount": 11
  }
]

`box_show`

One box's sections, and the assets in each.

CLI equivalent: refbox box show

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox box show 3

{
  "id": 3,
  "name": "Album art",
  "icon": "💿",
  "sections": [
    {
      "id": null,
      "name": null,
      "items": [
        {
          "id": 41,
          "type": "image",
          "name": "cover.jpg",
          "fileName": "cover.jpg",
          "source": {
            "type": "fileSystemPath",
            "path": "/Users/you/Pictures/cover.jpg"
          }
        }
      ]
    },
    {
      "id": 12,
      "name": "Covers",
      "items": [
        {
          "id": 42,
          "type": "palette",
          "name": "#F2EB8C, #DAFA10",
          "fileName": null,
          "source": null
        }
      ]
    }
  ]
}

`asset_show`

One asset: metadata, source, dimensions, and paths on disk.

CLI equivalent: refbox asset show

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox asset show 41

{
  "id": 41,
  "boxId": 3,
  "sectionId": 12,
  "type": "image",
  "name": "cover.jpg",
  "width": 2400,
  "height": 2400,
  "fileName": "cover.jpg",
  "source": {
    "type": "fileSystemPath",
    "path": "/Users/you/Pictures/cover.jpg"
  },
  "metadata": {
    "format": "JPEG",
    "colorSpace": "sRGB",
    "warnings": []
  },
  "sourcePath": "/Users/you/Library/Application Support/Refbox/media/cover.jpg",
  "thumbnailPath": "/Users/you/Library/Application Support/Refbox/media/cover-512.webp",
  "thumbnailKind": "derivative"
}

`asset_path`

An asset's file path, with thumbnail provenance when --thumb is used.

CLI equivalent: refbox asset path

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox asset path 41 --thumb

{
  "id": 41,
  "path": "/Users/you/Library/Application Support/Refbox/media/cover-512.webp",
  "thumbnailKind": "derivative"
}

`note_read`

A note asset's text.

CLI equivalent: refbox note read

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox note read 12

{
  "id": 12,
  "format": "text",
  "content": "Warm palette, low contrast"
}

`palette_read`

A palette asset's colors in its own format and normalized 8-digit hex.

CLI equivalent: refbox palette read

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox palette read 42

{
  "id": 42,
  "format": "hex",
  "values": [
    "#F2EB8C",
    "#DAFA10"
  ],
  "hex": [
    "#F2EB8CFF",
    "#DAFA10FF"
  ]
}

`search`

Find assets by file name, note text, or source URL.

CLI equivalent: refbox search

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox search "cover"

[
  {
    "id": 41,
    "boxId": 3,
    "boxName": "Album art",
    "type": "image",
    "name": "cover.jpg",
    "fileName": "cover.jpg",
    "source": {
      "type": "fileSystemPath",
      "path": "/Users/you/Pictures/cover.jpg"
    }
  }
]

`box_create`

Make a new box.

CLI equivalent: refbox box create

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox box create "Album art" --icon 💿

{
  "id": 3,
  "name": "Album art",
  "icon": "💿"
}

`box_rename`

Rename a box, or change its icon. One of the two is required.

CLI equivalent: refbox box rename

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox box rename 3 "Finished covers"

{
  "id": 3,
  "name": "Finished covers",
  "icon": null
}

`box_delete`

Send a box to the trash, with everything in it. Restore it with refbox restore.

CLI equivalent: refbox box delete

The MCP tool returns the same JSON value as the CLI command.

JSON output: Success

refbox box delete 5

{
  "deleted": 5
}

JSON output: Dry run

refbox box delete 5 --dry-run

{
  "dryRun": true,
  "changes": [
    "trash box 5 (Drafts) and everything in it"
  ]
}

`box_open`

Show a box in the Refbox window. Does not bring Refbox to the front.

CLI equivalent: refbox box open

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox box open 5

{
  "opened": 5
}

`section_create`

Make a section inside a box.

CLI equivalent: refbox section create

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox section create 3 "Covers"

{
  "id": 12,
  "boxId": 3,
  "name": "Covers"
}

`section_rename`

Rename a section.

CLI equivalent: refbox section rename

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox section rename 12 "Final covers"

{
  "id": 12,
  "name": "Final covers"
}

`section_delete`

Delete a section. Its assets stay in the box, outside every section.

CLI equivalent: refbox section delete

The MCP tool returns the same JSON value as the CLI command.

JSON output: Success

refbox section delete 12

{
  "deleted": 12
}

JSON output: Dry run

refbox section delete 12 --dry-run

{
  "dryRun": true,
  "changes": [
    "delete section 12, leaving its assets in the box, outside every section"
  ]
}

`asset_add`

Add files or web images to a box.

CLI equivalent: refbox asset add

The MCP tool returns the same JSON value as the CLI command.

JSON output: Success

refbox asset add 3 ~/Pictures/cover.jpg

{
  "boxId": 3,
  "added": [
    {
      "id": 41,
      "name": "cover.jpg"
    }
  ],
  "failures": [],
  "truncated": 0
}

JSON output: Dry run

refbox asset add 3 ~/Pictures/cover.jpg --dry-run

{
  "dryRun": true,
  "changes": [
    "add /Users/you/Pictures/cover.jpg to box 3"
  ]
}

`note_create`

Add a text note to a box. Reads standard input when --text is absent.

CLI equivalent: refbox note create

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox note create 3 --text "Warm palette, low contrast"

{
  "boxId": 3,
  "added": [
    {
      "id": 43,
      "name": "Warm palette, low contrast"
    }
  ],
  "failures": [],
  "truncated": 0
}

`note_update`

Replace a note's text. Reads standard input when --text is absent. Not an append: read the note first.

CLI equivalent: refbox note update

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox note update 43 --text "Use the warmer option"

{
  "id": 43,
  "truncated": false
}

`palette_create`

Add a palette of colors to a box. Reads standard input when --colors is absent.

CLI equivalent: refbox palette create

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox palette create 3 --colors "#F2EB8C, #DAFA10"

{
  "id": 42,
  "boxId": 3,
  "format": "hex",
  "hex": [
    "#F2EB8CFF",
    "#DAFA10FF"
  ]
}

`palette_update`

Replace a palette's colors. Reads standard input when --colors is absent. Not an append: read the palette first.

CLI equivalent: refbox palette update

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox palette update 42 --colors "#F2EB8C"

{
  "id": 42,
  "format": null,
  "hex": [
    "#F2EB8CFF"
  ]
}

`asset_move`

Move assets to another box, or into a section of the box they are in.

CLI equivalent: refbox asset move

The MCP tool returns the same JSON value as the CLI command.

JSON output: Success

refbox asset move 41 42 --to-section 12

{
  "moved": [
    41,
    42
  ],
  "toBoxId": null,
  "toSectionId": 12
}

JSON output: Dry run

refbox asset move 41 42 --to-section 12 --dry-run

{
  "dryRun": true,
  "changes": [
    "move asset 41 to section 12",
    "move asset 42 to section 12"
  ]
}

`asset_delete`

Send assets to the trash. Restore them with refbox restore.

CLI equivalent: refbox asset delete

The MCP tool returns the same JSON value as the CLI command.

JSON output: Success

refbox asset delete 41 42

{
  "deleted": [
    41,
    42
  ]
}

JSON output: Dry run

refbox asset delete 41 42 --dry-run

{
  "dryRun": true,
  "changes": [
    "trash asset 41 (image: cover.jpg)",
    "trash asset 42 (palette: #F2EB8C, #DAFA10)"
  ]
}

`trash_list`

What is in the trash, and the ids to restore it with.

CLI equivalent: refbox trash list

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox trash list

[
  {
    "id": "asset:41",
    "kind": "asset",
    "name": "cover.jpg",
    "boxName": "Album art",
    "deletedAt": "2026-08-14T14:32:18.000Z",
    "sizeBytes": 1843200
  },
  {
    "id": "box:5",
    "kind": "box",
    "name": "Drafts",
    "boxName": null,
    "deletedAt": "2026-08-14T14:35:02.000Z",
    "sizeBytes": 0
  }
]

`restore`

Take boxes or assets back out of the trash.

CLI equivalent: refbox restore

The MCP tool returns the same JSON value as the CLI command.

JSON output

refbox restore asset:41 box:5

{
  "restored": [
    {
      "kind": "asset",
      "id": 41,
      "name": "cover.jpg"
    },
    {
      "kind": "box",
      "id": 5,
      "name": "Drafts"
    }
  ]
}

MCP arguments use names instead of CLI positions. Get Box and Asset IDs from box_list, box_show, or search before you call a tool that needs them.

Commands Not Exposed as Tools

refbox trash empty — Delete everything in the trash for good, and free the disk space.
refbox token issue [--read-only] — Print a new read-only token. Give it to an agent that must not write.

These commands require a person to make the decision. Emptying the Trash cannot be undone, and issuing a token changes what an agent can access.

For all argument and flag details, see the CLI Reference.

CLI Reference

Complete command, argument, flag, and exit-code reference for the Refbox CLI.

Shortcuts

Complete keyboard shortcut reference for Refbox.