Developers spend a lot of time in the terminal. It’s where we write code, manage projects, run scripts, and increasingly, work alongside AI coding agents. But when we come across an interesting technical article or piece of documentation, that information often ends up in a browser tab, a bookmark, or a reading app that our other tools can’t easily access.
What if your reading library were available to those tools, too?
Today, we’re introducing the Bredbox CLI, a command-line interface designed for both developers and AI agents. It provides access to every operation in the Bredbox REST API, with predictable commands, structured output, and support for API tokens with fine-grained permissions.
You can use it to save an article without leaving your terminal, build scripts around your library, or let an AI agent search and work with content you’ve collected. And when you give an agent access, you get to decide exactly what it’s allowed to do.
The CLI is available now on npm, with source code on GitHub.
Getting started
The Bredbox CLI requires Node.js 22.18 or later. Install it globally with:
npm install -g @bredbox/cliTo authenticate, create a personal access token in your Bredbox account settings and run:
bredbox auth loginThe CLI validates the token and stores it locally. You can also provide a token through the BREDBOX_TOKEN environment variable, which is useful for scripts and AI agent environments.
Using the Bredbox API, including the CLI, requires a Bredbox Pro subscription.
Your reading library, from the command line
Let’s start with the basics. Say you’re researching a database problem and come across an article you want to save for later. Rather than leaving another browser tab open, you can add it directly:
bredbox saves add --url https://example.com/article --tag databasesYou can list saved articles:
bredbox saves list --filter inbox --type articleOr retrieve the content of a specific save as plain text:
bredbox saves content <save-id> --format textYou can also organize your library with tags and collections:
bredbox saves tags add <save-id> databases reference
bredbox collections items add <collection-id> --save-id <save-id>These aren’t separate copies of your data. Everything happens in the same Bredbox library you access through the web and mobile apps.
And because the CLI covers the entire Bredbox REST API, these examples are only a small part of what’s available.
Built for AI agents, not just humans
One of the most interesting uses for the CLI is giving AI agents access to your personal reading library.
AI coding agents are already comfortable working with command-line tools. They can run commands, inspect responses, and use the results as context for their work. The Bredbox CLI gives them a straightforward way to do the same with the technical articles, documentation, and other resources you’ve decided are worth keeping.
Imagine you’re working with an AI coding agent to investigate a performance problem. Six months earlier, you saved several articles about a similar issue. Instead of relying entirely on a fresh web search, your agent could use the Bredbox CLI to look through your saved library, retrieve relevant articles, and use that material to help investigate the problem.
The important difference is where the information comes from. These aren’t arbitrary search results. They’re resources you’ve previously encountered and chosen to preserve.
The CLI is designed to make this kind of interaction straightforward:
- Every API operation is available as a command. An agent can use the same capabilities exposed by the Bredbox REST API.
- Piped output is always JSON. Agents and scripts get predictable, structured responses rather than having to interpret human-readable terminal output.
- Commands are discoverable. The built-in help system describes available commands, options, and even the HTTP requests they send.
- Noninteractive behavior is explicit. Destructive commands require
--forcewhen running without a terminal, and exit codes distinguish successful requests, API errors, and invalid commands. - Authentication works through environment variables. Agents can use credentials supplied by their execution environment instead of going through an interactive login.
The CLI doesn’t require a special integration with a particular agent platform. Any agent capable of executing shell commands can potentially use it, provided its environment has the CLI installed and the necessary credentials.
Give agents access without giving up control
Of course, giving an AI agent access to your personal library raises an important question: what should it actually be allowed to do?
An agent that needs to find reference material probably doesn’t need permission to delete articles, change collections, or modify your library. You shouldn’t have to give it full access just to let it look something up.
Bredbox addresses this through fine-grained API token scopes.
When you create a personal access token, you can limit its permissions to the operations the agent needs. The CLI operates using that token, so the permissions are enforced by the Bredbox API rather than relying on the agent to follow instructions.
For example, you could create a read-only token for an AI coding agent. That agent could use the permitted API operations to search and retrieve material, but it wouldn’t be authorized to modify or delete your saved content.
For a different workflow, you might want an agent to save articles it discovers during research. You could give it the permissions needed to add content without providing unrestricted access to the rest of your library.
This distinction matters. Telling an AI agent not to delete something is not the same as making sure it doesn’t have permission to delete it.
With scoped tokens, the API provides that boundary regardless of what the agent attempts to do.
You can also assign different tokens to different agents or workflows, giving each only the access it requires. Because the CLI supports the BREDBOX_TOKEN environment variable, it’s straightforward to supply the appropriate token to each agent’s execution environment.
The result is a useful combination: agents can work with your personal library, but you remain in control of how much access they receive.
Predictable output for automation
The CLI also handles output differently depending on whether a human or another program is consuming it.
When you run a command in a terminal, results are formatted for readability. Lists appear as tables, objects as labeled fields, and dates are displayed relative to the current time.
When the output is piped to another process, the CLI automatically switches to JSON.
For example:
bredbox saves list --json | jq .An AI agent or shell script doesn’t have to parse decorative terminal output to understand the response. It receives structured data that can be processed directly.
You can explicitly select the output format using --json, --table, --pretty, or --compact, and use --output when saving responses to files.
There’s also a --dry-run option that shows the HTTP request a command would send without actually executing it. The authentication token is masked in the output.
These details might seem small, but they make a meaningful difference when the CLI is being used programmatically. Predictable commands, structured responses, and explicit failure behavior are exactly what automated tools need.
A CLI that grows with the API
Another important design choice is that we don’t manually implement every CLI command.
Instead, the commands are generated from the Bredbox REST API’s OpenAPI specification using Cloudflare Forge.
Each API operation becomes a command, with path parameters represented as positional arguments and request parameters exposed as flags. That means the CLI follows a consistent structure, and new API operations can become available through the CLI without requiring us to write each command individually.
We’ve also configured a scheduled workflow that checks the live API specification and opens a pull request when something changes.
This is useful for developers, but it’s also important for agents. A consistent command structure makes tools easier to discover and use, while generating commands from the API helps keep the command-line interface aligned with the capabilities of the underlying service.
To explore what’s available, run:
bredbox --help
bredbox saves --help
bredbox saves list --helpEach command’s help output includes the HTTP request it sends, making it easier to understand what’s happening under the hood.
The CLI runtime itself has no dependencies, and the project is available under the Apache 2.0 license.
One library, many ways to use it
The Bredbox CLI joins several other ways developers can interact with their libraries.
Our REST API provides direct programmatic access to your content. The MCP server lets compatible AI tools interact with your library through a standardized tool interface. Webhooks enable event-driven integrations, and n8n provides a visual way to build automated workflows.
The CLI offers a different approach: a command-line interface that both humans and agents can use.
You don’t need to choose one approach for everything. An AI assistant with MCP support might use our MCP server, while a coding agent that already executes shell commands might find the CLI a more natural fit. A custom application might use the REST API directly.
What matters is that Bredbox doesn’t require you to work through a single interface.
Your library contains information you’ve deliberately collected: articles you found useful, references you wanted to preserve, and ideas you might need again someday. That content should be available to the tools you choose, including AI tools, without requiring you to surrender control over it.
Try the Bredbox CLI
The Bredbox CLI is available now:
If you’re already using Bredbox Pro, you can create an API token and start using the CLI right away. If you want to experiment with AI agents, try creating a token with only the permissions your agent needs and making the CLI available in its environment.
We’re interested to see what people build with it, whether that’s a simple script for saving documentation, an AI-assisted research workflow, or something we haven’t thought of yet.
Your library belongs to you. Now your agents can work with it, too.