Example: Hello World

This article refers to SDK version v0.5.0. The current SDK version is N/A.

Overview

hello_world.py is the smallest possible working script built on the SDK: it logs in and lists the nodes in your company. It confirms your credentials and setup are correct, and it's the first thing to run after installing the SDK. If it doesn't work, nothing downstream will either.

This walkthrough reads through the script's source, runs it against your own fleet, and closes with two small changes you can make to build on it.

Get the script

The script lives in the SDK's examples/ directory. Download hello_world.py and save it locally: it's self-contained, with no dependencies beyond the SDK itself. If you haven't installed the SDK yet, see Getting started.

Set up credentials

Like every example script, hello_world.py reads the four Barbara API Credentials from environment variables. Instead of exporting them in your shell, you can also drop them in a .env file next to the script:

# .env
BBR_API_USERNAME=...
BBR_API_PASSWORD=...
BBR_API_CLIENT_ID=...
BBR_API_CLIENT_SECRET=...

The script loads .env from the current directory automatically, or you can point it at a different file with --env-file path/to/other.env. Variables already set in your shell always take precedence over the file. See Authenticate in the Getting started guide for what each credential is and where to find it.

Walk through the code

load_dotenv() is a small, dependency-free .env parser: it reads key=value lines and calls os.environ.setdefault(...) for each one, which is what makes an already-exported shell variable win over the file.

main() builds an ArgumentParser for --env-file, loads the dotenv file, then opens a client as a context manager:

with BarbaraClient.from_env() as client:
    try:
        client.api_version()
    except BarbaraAuthError as exc:
        raise SystemExit(f"Login failed — check your Barbara API Credentials: {exc}")
    print("Login OK.")

client.api_version() is called purely to fail fast: if your credentials are wrong, you get a clear "Login failed" message immediately, rather than an unrelated-looking error further down the script. Every example follows this same pattern, and every one prints Login OK. before doing anything else.

From there, listing nodes is a single call:

nodes = client.nodes.list()
print(f"Hello! You have {len(nodes)} node(s) in your fleet:")
for node in nodes:
    print(f"  - {node.node_name} ({node.id}) status={node.status}")

client.nodes.list() returns a single page of results. See client.nodes in the Reference for the paginate() alternative once your fleet outgrows one page.

Run it

python hello_world.py

Pass --env-file if your credentials live somewhere other than a .env file in the current directory.

Extend it

Two small changes turn this into a template for your own scripts:

• Filter the fleet. Pass a search term to the same call instead of listing everything: client.nodes.list(search="sensor"). Try narrowing it down to a subset of your nodes by name.
• Switch to the async client. Replace BarbaraClient with AsyncBarbaraClient, with with async with, and run main() inside asyncio.run(...). The rest of the script barely changes; see AsyncBarbaraClient in the Reference for the full signature.

Summary

You ran the smallest possible script built on the SDK: authenticate, open a client, and list your nodes.

The same pattern, a context manager plus a typed resource call, is what every other resource in the SDK follows, so what you just read scales directly to clusters, applications, and models.

For a script that reads everything about a single node, continue to Read a node's info and telemetry. For the full method list, see the Reference section.