oc_opsdevnz

OpenCollective client and CLI for OpsDev.nz. Resolves tokens from 1Password via op-opsdevnz. Use --staging/--test to target the staging.opencollective.com API.

Why

StartMeUp.NZ manages collectives through a lifecycle: onboard, support, offboard. Each collective is a YAML file. One command applies it. No clicking through the OpenCollective web UI. GitOps for fiscal hosting: versioned, reviewed, repeatable.

Features

• httpx GraphQL client with retries/backoff and redacted error messages.
• Environment guardrails: prod by default; for_staging() or --staging/--test required for staging.
• Token resolution via OC_SECRET_REF/OC_TOKEN using op-opsdevnz.
• CLI helpers for whoami, host organization upserts, collective creation/apply-to-host flows, and project creation from YAML/JSON.

Install

pip install oc-opsdevnz op-opsdevnz
# or editable while hacking in this repo
pip install -e .[dev]

CLI

export OC_SECRET_REF="op://startmeup.nz/api.opencollective.com/credential"  # or set OC_TOKEN

# Fetch an account/collective by slug
oc-opsdevnz whoami opsdevnz

# Show installed version
oc-opsdevnz version

# Create/update host orgs from YAML
oc-opsdevnz hosts --file hosts.yaml

# Create/update collectives and optionally apply to a host
oc-opsdevnz collectives --file collectives.yaml

# Create/update projects under a parent collective
oc-opsdevnz projects --file projects.yaml

Use --file or --config to point at any filename you prefer; defaults above are just examples. Use --staging/--test to hit staging, or --api-url to override explicitly. --prod remains accepted for explicitness but is the default.

Example YAML shapes

hosts.yaml (real staging values):

- name: StartMeUp.NZ
  slug: startmeup-nz
  description: Fiscal sponsor for OpsDev.NZ and NZ startups (staging)
  website: https://startmeup.nz
  currency: nzd
  tags: [fiscal-host, newzealand, aotearoa]

collectives.yaml (example):

- name: Example Collective
  slug: example-collective
  description: Example collective for testing.
  tags: [example, staging]
  host_slug: startmeup-nz
  apply_to_host: true
  host_apply_message: Please host this example collective on staging.

projects.yaml (example):

- name: Example Project
  slug: example-project
  parent_slug: example-collective
  description: Pilot project under the example collective.
  tags: [example, project]

Python API

from oc_opsdevnz import OpenCollectiveClient

client = OpenCollectiveClient.for_staging()
data = client.graphql("query { account(slug:\"example-collective\") { id slug name } }")

prod_client = OpenCollectiveClient.for_prod()  # default choice for CLI

Helpers for YAML-driven workflows:

from oc_opsdevnz import load_items, upsert_collective, upsert_host, upsert_project
from pathlib import Path

client = OpenCollectiveClient.for_staging()
for host in load_items(Path("hosts.yaml")):
    upsert_host(client, host)
for project in load_items(Path("projects.yaml")):
    upsert_project(client, project)

Documentation

Module documentation lives in docs/ and is served with Zensical:

# Install Zensical (add to dev dependencies if missing)
uv add --dev zensical

# Serve docs locally (human — not for AI assistants)
uv run zensical serve

# Build docs to verify they render without errors
uv run zensical build

See zensical.toml for site configuration and navigation structure.

Development

uv sync --extra dev
uv run python -m pytest tests/ -v

To run linting:

uv run ruff check src tests

License

Apache-2.0 © OpsDev.nz