Refbox
Command Line

CLI Reference

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

This page lists every command available in the refbox command-line tool. See Command Line Access for installation and first-use instructions.

Global Flags

These flags work with every command:

  • --help — Show this help. Also -h.
  • --version — Show this command's and the running app's versions. Also -v.

Commands

refbox status

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

Usage: refbox status

Examples

refbox status

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
  }
}

refbox box list

Every box: id, name, and item count.

Usage: refbox box list

Examples

refbox box list

JSON output

refbox box list

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

refbox box show

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

Usage: refbox box show [id] [--name <value>]

Arguments

  • id (optional) — Box id, from box list. Or name the box with --name.

Command flags

  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox box show 3
refbox box show --name "Album art"

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
        }
      ]
    }
  ]
}

refbox asset show

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

Usage: refbox asset show <id>

Arguments

  • id (required) — Asset id, from box show.

Examples

refbox asset show 41

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"
}

refbox asset path

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

Usage: refbox asset path <id> [--thumb]

Arguments

  • id (required) — Asset id, from box show.

Command flags

  • --thumb — Prefer a small version (512px). Falls back to the source file when none exists.

Examples

refbox asset path 41
refbox asset path 41 --thumb

JSON output

refbox asset path 41 --thumb

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

refbox note read

A note asset's text.

Usage: refbox note read <id> [--html]

Arguments

  • id (required) — Asset id, from box show.

Command flags

  • --html — Return the original HTML instead of plain text.

Examples

refbox note read 12
refbox note read 12 --html

JSON output

refbox note read 12

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

refbox palette read

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

Usage: refbox palette read <id>

Arguments

  • id (required) — Asset id, from box show.

Examples

refbox palette read 12

JSON output

refbox palette read 42

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

refbox search

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

Usage: refbox search <query> [--in-box <value>]

Arguments

  • query (required) — Text to look for.

Command flags

  • --in-box <value> — Look in this box only, by id. Reads one box instead of every one.

Examples

refbox search "moodboard"
refbox search "sunset" --in-box 3

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"
    }
  }
]

refbox box create

Make a new box.

Usage: refbox box create <name> [--icon <value>]

Arguments

  • name (required) — What to call it.

Command flags

  • --icon <value> — One character for the sidebar. Defaults to 📁.

Examples

refbox box create "Album art"
refbox box create "Album art" --icon 🎨

JSON output

refbox box create "Album art" --icon 💿

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

refbox box rename

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

Usage: refbox box rename [id] [new-name] [--icon <value>] [--name <value>]

Arguments

  • id (optional) — Box id, from box list. Or name the box with --name.
  • new-name (optional) — The new name.

Command flags

  • --icon <value> — One character for the sidebar, usually an emoji.
  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox box rename 3 "Album art"
refbox box rename 3 --icon 🎨
refbox box rename 3 "Album art" --icon 🎨
refbox box rename --name "Drafts" "Album art"

JSON output

refbox box rename 3 "Finished covers"

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

refbox box delete

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

Usage: refbox box delete [id] [--name <value>] [--dry-run]

Arguments

  • id (optional) — Box id, from box list. Or name the box with --name.

Command flags

  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.
  • --dry-run — Print what would change and stop. Nothing is written.

Examples

refbox box delete 5
refbox box delete --name "Drafts"
refbox box delete 5 --dry-run

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"
  ]
}

refbox box open

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

Usage: refbox box open [id] [--name <value>]

Arguments

  • id (optional) — Box id, from box list. Or name the box with --name.

Command flags

  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox box open 5
refbox box open --name "Album art"

JSON output

refbox box open 5

{
  "opened": 5
}

refbox section create

Make a section inside a box.

Usage: refbox section create [box-id] <section-name> [--name <value>]

Arguments

  • box-id (optional) — Box id, from box list. Or name the box with --name.
  • section-name (required) — What to call the section.

Command flags

  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox section create 3 "Covers"
refbox section create --name "Album art" "Covers"

JSON output

refbox section create 3 "Covers"

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

refbox section rename

Rename a section.

Usage: refbox section rename <id> <new-name>

Arguments

  • id (required) — Section id, from box show.
  • new-name (required) — The new name.

Examples

refbox section rename 12 "Covers"

JSON output

refbox section rename 12 "Final covers"

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

refbox section delete

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

Usage: refbox section delete <id> [--dry-run]

Arguments

  • id (required) — Section id, from box show.

Command flags

  • --dry-run — Print what would change and stop. Nothing is written.

Examples

refbox section delete 12
refbox section delete 12 --dry-run

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"
  ]
}

refbox asset add

Add files or web images to a box.

Usage: refbox asset add [box-id] <path> [--name <value>] [--dry-run]

Arguments

  • box-id (optional) — Box id, from box list. Or name the box with --name.
  • path (required) — File paths, URLs, or a quoted pattern like '*.png'.

Command flags

  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.
  • --dry-run — Print what would change and stop. Nothing is written.

Examples

refbox asset add 3 ~/Pictures/cover.jpg
refbox asset add --name "Album art" ~/Pictures/cover.jpg
refbox asset add 3 https://example.com/poster.jpg
refbox asset add 3 '*.png' --dry-run

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"
  ]
}

refbox note create

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

Usage: refbox note create [box-id] [--text <value>] [--markdown] [--name <value>]

Arguments

  • box-id (optional) — Box id, from box list. Or name the box with --name.

Command flags

  • --text <value> — The note's text.
  • --markdown — Read the text as markdown: headings, lists, and - [ ] task lists.
  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox note create 3 --text "warm palette, low contrast"
refbox note create --name "Album art" --text "warm palette"
refbox note create 3 --markdown --text "- [ ] frame the shot"

JSON output

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

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

refbox note update

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

Usage: refbox note update <id> [--text <value>] [--markdown]

Arguments

  • id (required) — Asset id, from box show.

Command flags

  • --text <value> — The note's text.
  • --markdown — Read the text as markdown: headings, lists, and - [ ] task lists.

Examples

refbox note update 12 --text "warm palette, low contrast"
refbox note update 12 --markdown --text "- [x] frame the shot"

JSON output

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

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

refbox palette create

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

Usage: refbox palette create [box-id] [--colors <value>] [--format <value>] [--name <value>]

Arguments

  • box-id (optional) — Box id, from box list. Or name the box with --name.

Command flags

  • --colors <value> — The colors, separated by commas or newlines. Hex, rgb(), or hsl().
  • --format <value> — How values are copied out: hex, hexNoHash, rgb, or hsl. Defaults to the app's setting.
  • --name <value> — The box's name, in place of its id. Exact match, ignoring case.

Examples

refbox palette create 3 --colors "#F2EB8C, #DAFA10"
refbox palette create --name "Album art" --colors "#F2EB8C"
refbox palette create 3 --colors "rgb(242, 235, 140)" --format rgb

JSON output

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

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

refbox palette update

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

Usage: refbox palette update <id> [--colors <value>] [--format <value>]

Arguments

  • id (required) — Asset id, from box show.

Command flags

  • --colors <value> — The colors, separated by commas or newlines. Hex, rgb(), or hsl().
  • --format <value> — How values are copied out: hex, hexNoHash, rgb, or hsl. Defaults to the app's setting.

Examples

refbox palette update 12 --colors "#F2EB8C, #DAFA10"
refbox palette update 12 --format hsl --colors '#F2EB8C'

JSON output

refbox palette update 42 --colors "#F2EB8C"

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

refbox asset move

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

Usage: refbox asset move <id> [--to-box <value>] [--to-section <value>] [--dry-run]

Arguments

  • id (required) — Asset ids, from box show.

Command flags

  • --to-box <value> — Target box id.
  • --to-section <value> — Target section id, or none to take them out of every section.
  • --dry-run — Print what would change and stop. Nothing is written.

Examples

refbox asset move 41 42 --to-box 5
refbox asset move 41 --to-section 12
refbox asset move 41 42 --to-section none --dry-run

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"
  ]
}

refbox asset delete

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

Usage: refbox asset delete <id> [--dry-run]

Arguments

  • id (required) — Asset ids, from box show.

Command flags

  • --dry-run — Print what would change and stop. Nothing is written.

Examples

refbox asset delete 41 42
refbox asset delete 41 --dry-run

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)"
  ]
}

refbox trash list

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

Usage: refbox trash list

Examples

refbox trash list

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
  }
]

refbox restore

Take boxes or assets back out of the trash.

Usage: refbox restore <id>

Arguments

  • id (required) — Ids from trash list. Use box:3 or asset:41 to be explicit.

Examples

refbox restore 41
refbox restore box:3 asset:41

JSON output

refbox restore asset:41 box:5

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

refbox trash empty

Delete everything in the trash for good, and free the disk space.

Usage: refbox trash empty

This command is available only in the CLI. It is not exposed as an MCP tool.

Examples

refbox trash empty

JSON output

refbox trash empty

{
  "boxes": 1,
  "assets": 3,
  "filesUnlinked": 3,
  "bytesFreed": 4812390
}

refbox token issue

Print a new read-only token. Give it to an agent that must not write.

Usage: refbox token issue [--read-only]

This command is available only in the CLI. It is not exposed as an MCP tool.

Command flags

  • --read-only — Required. The only kind of token that can be issued.

Examples

refbox token issue --read-only

JSON output

refbox token issue --read-only

{
  "token": "refbox_ro_example-token-not-valid",
  "scope": "read"
}

MCP Mode

Serve these commands as MCP tools over stdin/stdout, for an agent with no shell (Claude Desktop, Cursor).

refbox mcp

Exit Codes

CodeMeaning
0success
1the request failed (reason on stderr)
2the command or arguments were wrong
3Refbox is not running, or Command Line Access is off

Command Line Access

Install and use the Refbox CLI to read and change Boxes from a terminal or local agent.

MCP Setup

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