Inspect the Store with cb-cli

Hands-on: connect cb-cli to a running node with an API key, then inspect and navigate its Store.

In this tutorial you will use the cb-cli command-line tool to read and navigate the live in-memory Store of a running ControlBird node. By the end you will have walked the entity hierarchy, run a filtered query, and read individual fields from a specific entity, from your own computer.

Looking for full details?

This is a hands-on tutorial. For the complete reference, covering every field, option, and edge case, see the CLI Tools reference.

What you'll need

A running ControlBird node and a user account on it.
Docker on the computer you will run cb-cli from.
The node's https:// address, the one you open it at in your browser. A self-hosted node, such as a Community Edition node, serves it at https://<host>:3443.

Step by step

Create an API key. Sign in to your node and open API Keys from the user section of the start menu (on a phone, from the profile sheet). Enter a name such as laptop cb-cli, keep the default expiry of 90 days, and select Create key. Select Copy key: the key is shown only once.
Save the key to a private file. Create a file only you can read:
```
mkdir -p ~/.controlbird
touch ~/.controlbird/cb-key
chmod 600 ~/.controlbird/cb-key
```
Open ~/.controlbird/cb-key in a text editor, paste the key as its only content, and save it. Then select Done in the API Keys window.
Define a cb-cli alias. cb-cli runs from its container image. Replace the address with your node's and <version> with the version your node runs:
```
alias cb-cli='docker run --rm -it --user "$(id -u):$(id -g)" -e CB_NODE_URL=https://node.example.com -e CB_API_KEY_FILE=/run/cb-key -v "$HOME/.controlbird/cb-key:/run/cb-key:ro" controlbird/cli:<version>'
```
--user runs the tool as you, so it can read your private key file.
By default a self-hosted node uses a self-signed certificate the tool does not trust. In the node's Certificate Manager, open the Web Server tab, select Download node certificate, and save the file as ~/.controlbird/node.pem. Then define the alias with the node's port 3443 and that certificate:
```
alias cb-cli='docker run --rm -it --user "$(id -u):$(id -g)" -e CB_NODE_URL=https://192.168.1.10:3443 -e CB_API_KEY_FILE=/run/cb-key -e CB_NODE_CA_FILE=/run/node.pem -v "$HOME/.controlbird/cb-key:/run/cb-key:ro" -v "$HOME/.controlbird/node.pem:/run/node.pem:ro" controlbird/cli:<version>'
```
The node replaces this certificate about every 795 days; download it again when it does. See Connecting to a Community Edition node. Check the connection:
```
cb-cli -c "PING"
```
Expected result: PONG, printed once the tool has connected to your node with your key. If you see an error instead, look it up in the CLI Tools reference troubleshooting table.
Walk the entity hierarchy with cb-cli. Render the top two levels of the tree, starting from the Root entity, with entity IDs shown:
```
cb-cli -c "TREE --max-depth 2 --show-ids"
```
Expected result: an ASCII tree drawn with ├ and └ connectors. TREE walks the Children field (an EntityList) recursively from Root, and --show-ids appends each entity's ID next to its Name. Note an ID near the top of the tree: you will use one in a later step.
Run a filtered query with cb-cli. Query entities of a type, returning only the fields you ask for, in a table. For example, list users:
```
cb-cli -c "SELECT User --fields Name,Active --format table --show-ids"
```
To narrow the result, add a CEL expression with --filter. For example, to find a device by name:
```
cb-cli -c "SELECT ExampleDevice --filter \"Name == 'Motor-1'\" --fields Name,Description --format csv"
```
Expected result: a table (or CSV) listing the matching entities and the requested fields. If you omit --fields, SELECT returns the Name field by default. Swap --format for json, ids, or count depending on what you need.
Read specific fields with the cb-cli REPL. Launch the interactive client:
```
cb-cli
```
At the kernel> prompt, read named fields from an entity by ID. Using an ID you noted from the tree in step 4:
```
GET 42 name description
```
You can also run a query directly from the REPL with a CEL filter, list the available commands with HELP, and leave with EXIT:
```
FIND ExampleDevice 'Name == "Motor-1"'
HELP
EXIT
```
Expected result: GET prints the requested field values for the entity, FIND lists matching entities, and EXIT returns you to your shell prompt. Recall earlier commands in the session with the up arrow.
For a navigable view of the hierarchy, enter TREE at the prompt without -c. Use Up/Down to select an entity, Left/Right to collapse or expand it, Enter to open its fields, the mouse wheel to scroll, and Esc to return to the prompt. In the field view, use Up/Down to select a field and Enter to edit and save it. The field view also shows the last writer and write time; Esc cancels an edit or returns to the tree.

Cap your depth and limits on large data

TREE --max-depth 0 and SELECT ... --limit 0 both mean unlimited, and can be slow or memory-heavy on a large Store. Field indirection in SELECT (for example Parent->Name) adds overhead per entity, so queries returning thousands of entities with many fields can be slow. For interactive inspection, always set a sensible --max-depth and --limit, as the steps above do.

Next steps

You now know how to inspect the Store of a running node from the command line. To go deeper:

Read the full CLI Tools reference for every command and flag, the cb-wal, cb-snapshot and cb-files maintenance tools, cb-mcp for AI assistants, and managing and revoking API keys.
Learn how the data you just browsed is structured in the Data Model.