2. Setup¶

Two surfaces, one install: the datavo CLI and the datavo_sdk Python client. Start with the CLI to prove you can reach a server, then build the client the rest of the guide uses.

Install¶

uv add datavo-cli
# or
pip install datavo-cli

datavo-cli depends on datavo-sdk[entra], so this installs the datavo command, the Python client and MSAL together — everything Entra sign-in needs. The chapters also use numpy for example payloads, and torch only where a DataLoader or a .pth key appears.

datavo auth login

That is the whole setup. The CLI already points at https://prod.datavo.io, so there is nothing to configure first — auth login needs no flags either: against an Entra server it runs the interactive login and caches the refresh token in ~/.datavo/msal_cache.json.

Using a different instance

Only if you have been told to. A profile stores a name and URL in `~/.datavo/config.json`:

datavo config set dev --url https://dev.datavo.io
datavo config use dev

Omit the profile name and it is the URL's hostname. `DATAVO_API_BASE_URL` overrides the profile for one command, and `DATAVO_PROFILE` selects a saved one. `config set` also caches the server's public config in `~/.datavo/server_config.json`.

Check connectivity¶

Three commands, in order — each fails differently, so together they say where a problem is:

datavo config show       # which server you point at, and the Entra settings it advertised
datavo auth status       # whether a credential is in place locally
datavo sample-store list # the first authorized round trip to the server

The first two read local state; sample-store list is the one that actually calls the server, so it tests reachability, authentication and your role at once. A 403 there means you got through and your role is the limit: a reader browses, reads and downloads, and a contributor also creates stores, imports, attaches and builds datasets. Chapter 15 tells the whole access story — roles, teams, sharing and tokens.

The Python client¶

Everything from chapter 4 on is Python. Constructing a client is all the authentication you do: it discovers the tenant, client id and audience from the server's /config and reuses the MSAL cache the CLI just wrote, so it refreshes silently.

from datavo_sdk import DatavoClient

client = DatavoClient()

It defaults to https://prod.datavo.io; pass server_url= only to reach a different instance. Two variations:

# headless — device code instead of a browser
from datavo_sdk import login_entra
client = DatavoClient(token_provider=login_entra(device_flow=True))

# a program — CI, a scheduled job — runs on a run token, never on your login (chapter 15)
client = DatavoClient(auth_token=run_token)

Use it as a context manager (with DatavoClient(...) as client:) in a short script, and keep it alive for as long as you iterate data — iteration is lazy and streams through it.

Reads can also build their own client: omit client= from SampleStream.from_dataset(...) and it falls back to DATAVO_API_BASE_URL / DATAVO_AUTH_TOKEN, or to the active CLI profile. That is what makes a script portable between your machine and CI.

Run the examples¶

Each chapter from here has a script. They take the server from DATAVO_SERVER, then the active CLI profile, then a local server — deliberately not the production default the client uses, since every script creates and deletes a store. Name the server you mean:

DATAVO_SERVER=https://dev.datavo.io python examples/01_ingest_source.py

Every script creates its own throwaway store, prints what it does, and deletes what it created, so they are safe to run repeatedly against a shared server.

Pitfalls¶

A profile pointing somewhere else. Commands target whichever profile is active. Check datavo config list before anything that writes, or scope one command with DATAVO_PROFILE=<name> datavo ….
Skipping the CLI login. The Python client can log in interactively too, but doing it once through the CLI keeps scripts non-interactive afterwards.
Your login inside a program. A CI job or a container must not carry your identity token: it expires within the hour, and it can do everything you can. Mint the program a run token (chapter 15).

Next: 3. Download data — get existing data onto your disk.