Use the command line

Some of the best tools are the ones you can reach without leaving what you’re doing. The Bredbox CLI puts your library one command away in any terminal: list your Inbox, save a link, search for that article you half remember, or pipe your saves into another tool.

Every operation in the REST API is a command, so anything you can do with the API you can do from the CLI, without writing any HTTP requests.

Before you start

You need:

The Pro plan, which includes developer features. See Manage your plan and data.
Node.js 22.18 or later.

Install the CLI

Install it globally with npm:

npm i -g @bredbox/cli

This gives you the bredbox command. To try it without installing, run it through npx instead:

npx @bredbox/cli saves list

The CLI signs in with an API token.

Create a token under Settings → Tokens. Include the user:read scope, which the CLI uses to check the token, plus the scopes for what you plan to do: saves:read and saves:write cover most everyday use.
Run:
Terminal window
```
bredbox auth login
```
Paste the token when asked. It isn’t shown as you type.

The CLI checks the token with Bredbox and saves it in a config file: ~/.config/bredbox/config.json on macOS and Linux, or %APPDATA%\bredbox\config.json on Windows.

In a script, pipe the token in instead of typing it:

bredbox auth login < token.txt

Or skip saving it altogether and set the BREDBOX_TOKEN environment variable, which takes precedence over a saved token. This is the usual choice for CI jobs and other automation.

To see which token is in use, run bredbox auth status. To delete the saved token, run bredbox auth logout.

Run your first commands

Commands follow the shape of the API: a group, sometimes a subgroup, then an action.

# What's in my Inbox?
bredbox saves list --filter inbox

# Save a link with a tag
bredbox saves add --url https://example.com/article --tags reading

# Search the whole library
bredbox saves search --q "connection pooling"

# Read a save as plain text
bredbox saves content <save-id> --format text

# Add a save to a collection
bredbox collections items add <collection-id> --save-id <save-id>

Replace <save-id> and <collection-id> with real IDs. List and search results show the ID of each save, and bredbox collections list shows the IDs of your collections.

Get help from the CLI

The CLI documents itself, so you don’t need to memorize anything:

bredbox --help lists every group.
bredbox saves --help lists the commands in a group.
bredbox saves list --help lists the options for one command, along with the API request it sends.

How options work

If you know the REST API, you already know the CLI’s options:

IDs in the API’s address are given in order, without a flag: bredbox saves get <save-id>.
Everything else is a flag, written in lowercase with hyphens: the API’s per_page is --per-page.
Lists repeat the flag: --tags one --tags two.
Yes or no options are turned off with --no-: --no-is-favorite.
Nested values are written as JSON: --location '{"kind":"pdf","page":3}'.
Values from a file start with @: --html @page.html.

Choose the output

In a terminal, the CLI formats results for reading. Lists print as tables, with a note telling you how to get the next page, and single items print as labeled fields with dates like “3 days ago.”

When you pipe the output to another program or save it to a file, it switches to JSON, so scripts always get something they can parse. For example, to print the address of every save in your Inbox with jq:

bredbox saves list --filter inbox | jq -r '.items[].url'

You can override the format either way:

--json prints JSON in a terminal.
--table prints tables and fields even when piped.
--pretty and --compact choose indented or single-line JSON.

Files, such as an export archive, need somewhere to go. Use --output:

bredbox exports download <export-id> --output export.zip

To see the request a command would send without sending it, add --dry-run. Your token is hidden in what it prints.

Delete things safely

Commands that delete something ask you to confirm first. When there’s no one to ask, such as in a script, they refuse to run unless you add --force (or -f):

bredbox saves delete <save-id> --force

Deleted saves go to Trash, where you can restore them for 30 days.

Use it in scripts

The CLI reports how each command went through its exit code, so scripts can react to failures:

Code	Meaning
`0`	The command worked.
`1`	Bredbox returned an error, or you didn’t confirm a deletion.
`2`	The command itself was wrong, such as a misspelled option.

These environment variables change how it runs:

Variable	What it does
`BREDBOX_TOKEN`	The API token to use, instead of a saved one
`BREDBOX_API_URL`	The API address (default `https://api.bredbox.app/v2`)
`BREDBOX_CONFIG`	Where the config file lives

Set NO_COLOR to turn off bold headings in the output.

When a command fails

Check these common causes:

“No access token”: run bredbox auth login, or set BREDBOX_TOKEN.
auth login rejects the token: make sure you copied all of it, and that it has the user:read scope.
An insufficient_scope error: the token is missing the scope named in the error. Create a new token that includes it.
The token stopped working: it may have expired or been revoked. See When a token stops working.
bredbox isn’t found after installing: check that npm’s global folder is on your PATH, or run the CLI through npx @bredbox/cli.