Inspect the Store from the Shell

Hands-on: use cb-cli, cb-tree, and cb-select in the browser Shell.

In this tutorial you will open the browser-based Shell app inside the ControlBird platform and use three command-line tools (cb-cli, cb-tree, and cb-select) to read the live in-memory Store without leaving the running system. By the end you will have launched a terminal session, walked the entity hierarchy, run a filtered query, and read individual fields from a specific entity. Everything happens in the browser, against the kernel your platform is already connected to.

Looking for full details?

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

What you'll need

  • A running ControlBird platform you can sign in to, with the kernel up and reachable.
  • An account whose role grants the app.shell permission. This permission is included with the Owner role. Without it the Shell app will not let you spawn a session.
  • A few minutes and a desktop browser. The Shell works on mobile too, but the wider terminal on a desktop makes the tree and table output easier to read.

No setup flags required

When you launch a tool from the Shell, the kernel address (KERNEL_ADDRESS), node identity (NODE_ID), data directory (DATA_DIR), and your user attribution are all pre-configured in the session environment. The cb-* binaries are already on PATH via CB_BIN_DIR, so you can run them by name with no flags.

Step by step

  1. Open the Shell app. From the ControlBird platform UI, open the Shell app. If you do not see it, your role is missing the app.shell permission.

    Expected result: the Shell app opens with a terminal area and a session tab bar.

  2. Start a Bash session. Click the + button to create a new Bash shell session. (The chevron dropdown next to it lets you launch Claude Code, Codex, or OpenCode instead, when those tools are installed and authenticated, though you do not need them for this tutorial.)

    Expected result: a new session tab opens and you are dropped at a shell prompt, ready for input.

  3. Confirm the environment is wired up. Type the following and press Enter: 

    echo $KERNEL_ADDRESS

    Expected result: this prints the kernel address (for example localhost:9100, or a comma-separated failover list). This confirms the tools will find the kernel. Any writes you make are attributed to you in the audit trail.

  4. Walk the entity hierarchy with cb-tree. Render the top two levels of the tree, starting from the Root entity, with entity IDs shown: 

    cb-tree --max-depth 2 --show-ids

    Expected result: an ASCII tree drawn with ├ and └ connectors. cb-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 the last step.

  5. Run a filtered query with cb-select. Query entities of a type, returning only the fields you ask for, in a table. For example, list users: 

    cb-select --entity-type 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-select --entity-type 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, cb-select returns the Name field by default. Swap --format for json, ids, or count depending on what you need.

  6. 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 the bash prompt. Interactive history is kept in ~/.kernel_history, so you can recall earlier commands with the up arrow.

  7. Close the session. When you are done, click the X on the session tab. The terminal session ends, and all sessions are cleaned up when you close the Shell app or the connection drops.

Click IDs and links in the output

The Shell terminal makes output interactive. Click an entity ID (shown in hex) to open the Entity Details window for that entity, and click a URL to open it in a new browser tab. This is the fastest way to jump from a cb-tree or cb-select result straight into the UI.

Cap your depth and limits on large data

cb-tree --max-depth 0 and cb-select --limit 0 both mean unlimited, and can be slow or memory-heavy on a large Store. Field indirection in cb-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.

Session limits

A single connection supports up to 4 concurrent terminal sessions, with a platform total of up to 20 sessions across all users. Close sessions you are no longer using to stay within these limits.

On mobile

If you open the Shell on a touch device or a narrow viewport (600 px or less), the font shrinks so 80-column output fits, and a soft-key bar appears at the bottom with Esc, Tab, Ctrl, arrow keys, and the |, /, ~, and - characters. To send a control sequence such as Ctrl+C, tap Ctrl (it latches), then tap the letter.

Next steps

You now know how to inspect the Store live from the browser. To go deeper: