Quickstart

If you’re setting up a new laptop, follow this in order. Should take ~5 minutes.

1. Install 1Password and the op CLI

The op CLI is what constellation-utils uses behind the scenes to fetch credentials.

brew install --cask 1password
brew install 1password-cli

Open the 1Password desktop app and sign in with your @constellationlab.io account. Then enable CLI integration:

Settings → Developer → “Integrate with 1Password CLI” (toggle ON)

With that toggle on, the op CLI piggybacks on the desktop app’s biometric-unlocked session. No op signin command needed.

2. Verify you have access

op whoami
op vault list

op vault list should include Engineering. If it doesn’t, ask Reese in #ml-ops to grant you access.

A direct read should also work:

op read 'op://Engineering/R2 Testing/access_key_id'

It should print a long string (the access key). If it errors, fix that before continuing — nothing else will work.

3. Install the package

As a CLI tool on your laptop:

uv tool install "constellation-utils @ git+https://github.com/constellationlab/constellation-utils"

As a runtime dependency of another project:

uv add "constellation-utils @ git+https://github.com/constellationlab/constellation-utils"

These specs always resolve against the main branch on a fresh install. To force uv to refetch when you know main has moved (uv caches resolved git refs), pass --refresh-package constellation-utils.

4. Smoke test

constellation doctor

Expected output:

profile: testing    backend: OpCLIBackend
✓ R2 (testing) reachable
  endpoint      : https://....r2.cloudflarestorage.com
  bucket        : constellation-data-test
  region        : auto
  access_key_id : AKIA…XX

If you see ✓, you’re done — go write code.

If you see ✗, the error message tells you what’s missing. Most often: you skipped step 1 (CLI integration toggle) or step 2 (vault access).

5. Use it in code

from constellation_utils import secrets

r2 = secrets.r2()

# r2 is a frozen Pydantic model. Use .endpoint, .access_key_id, etc.
print(r2.bucket)

The first call shells out to op to fetch values; subsequent calls in the same Python process are cached automatically.

What about CI / rigs / production?

You don’t run those by hand — there are different auth paths for those environments. See Concepts → Authentication modes for the full picture.