Command Line Access

Command Line Access lets a terminal, script, or local agent read and change your Refbox data. The refbox command connects only to the Refbox app running on your computer.

Enable the CLI

refbox status

Refbox must remain open and Command Line Access must remain enabled. If the command is missing or points to an older copy of Refbox, the setting shows a repair message and a Try again action.

First Commands

Start by listing Boxes, then use the returned IDs to inspect their contents:

refbox box list
refbox box show 3
refbox asset show 41

Most commands that take a Box ID also accept an exact Box name with --name:

refbox box show --name "Album art"

Use --help for the current command list, or add it to one command for its arguments and examples:

refbox --help
refbox asset move --help

JSON Output

Every successful command writes one JSON value to standard output. You do not need an output-format flag:

refbox box list
refbox search "sunset"
refbox asset path 41 --thumb

Every failure writes one JSON error object to standard error and exits with a non-zero code. refbox --help remains readable command help rather than a command result.

Common Workflows

Find and inspect an Asset

refbox search "moodboard"
refbox asset show 41
refbox asset path 41 --thumb

asset path --thumb returns an object whose path points to a 512 px derivative when one exists. It falls back to the source file when no derivative is available. The thumbnailKind field states which path was returned.

Add files to a Box

Preview a bulk change before you run it:

refbox asset add 3 '*.png' --dry-run
refbox asset add 3 '*.png'

The command accepts local file paths, web-image URLs, and quoted file patterns.

Create or update a Note

refbox note create 3 --text "warm palette, low contrast"
refbox note create 3 --markdown --text "- [ ] frame the shot"
refbox note read 12
refbox note update 12 --text "warm palette, high contrast"

If --text is absent, Note commands read standard input. An update replaces the complete Note; it does not append text.

Create or update a Palette

refbox palette create 3 --colors "#F2EB8C, #DAFA10"
refbox palette read 12
refbox palette update 12 --format hsl --colors "#F2EB8C"

If --colors is absent, Palette commands read standard input. An update replaces the complete color list. Valid formats are hex, hexNoHash, rgb, and hsl.

Safe Changes and the Trash

Commands that can affect many Assets support --dry-run. Use it first to print the planned change without writing anything.

Deleting a Box or Asset sends it to the Trash:

refbox asset delete 41 --dry-run
refbox asset delete 41
refbox trash list
refbox restore asset:41

refbox trash empty permanently removes all Trash contents. It cannot be undone.

Read-Only Tokens

The default CLI connection can read and change data. Create a read-only token when a tool or agent must only inspect Refbox:

refbox token issue --read-only

Pass the token through the REFBOX_TOKEN environment variable for that tool. A read-only token cannot run write commands.

Scope and Limits

The CLI works with Boxes, Sections, and Assets. It can read and update Notes and Palettes. It does not expose Groups, canvas Frames, or the position of an Asset on the canvas.

Opening a Box with refbox box open changes the Box shown in Refbox, but it does not bring the Refbox window to the front.

Connection Problems

Exit code 3 means that Refbox is not running or Command Line Access is off.

If your shell reports that refbox was not found:

1. Confirm that Command Line Access is enabled.
2. Restart the terminal.
3. Return to Settings > Data > Access Control and use Try again if Refbox offers it.

See the CLI Reference for every command and the MCP Setup page for clients that use Model Context Protocol.