semble — general-purpose Semble API CLI

semble is a git-style CLI (and importable library) for the Semble public GraphQL API. It models Semble's own concepts, not any one clinic's workflow.

A "Responsible Clinician" is not special. In Semble it is just a patient relationship with a label that points at a contact. So use semble patient relationship add … --label "Responsible Clinician". Whatever a downstream app does with that relationship is that app's concern, not the CLI's.

Configuration

Precedence: flags > env > config file (`~/.config/semble/config.json`) > built-in presets (sandbox, prod). Env vars: SEMBLE_PROFILE, SEMBLE_OPEN_URL, SEMBLE_TOKEN. Pick a profile per-command with --profile <name>. Credentials are auto-discovered: with no --env-file/$SEMBLE_ENV_FILE, the CLI walks UP from the cwd to the project root and loads the nearest .env or .claude/.env — so it works from any subdirectory, run by any agent, with no source or cd. It only fills vars that aren't already set (real env vars and flags win).

• Open GraphQL API (x-token): patient, contact, user. Set token (env SEMBLE_TOKEN).

Commands

# Look up records (search/list auto-paginate; --limit caps results)
semble patient search "smith" [--limit 5] [--json]      # omit the query to list patients
semble patient get <patientId> [--json]
semble contact search "clinic" [--limit 5] [--json]      # name/email/telephone/specialization/id no.
semble contact get <contactId>
semble user list [--limit 5]                             # clinicians/staff (a relationship can point at a user)
semble user get <userId>

# Patient relationships (writes need --confirm). <accountId> = a contact OR user id.
semble patient relationship list <patientId> [--resolve]
semble patient relationship add <patientId> <accountId> --label "Responsible Clinician" --confirm
semble patient relationship update <patientId> <relId> <accountId> --confirm
semble patient relationship remove <patientId> <relId> --confirm

Run semble help or semble <command> --help for full usage. stdout is data, stderr is messages; exit 0 success · 1 runtime error · 2 usage error.

Notes

• Writes against the open API are deliberately gated (--confirm).
• The --json flag on any command emits machine-readable output for piping.
• Tracing. Every command appends a metadata line (method, URL, status, timing — no bodies) to

`.semble/trace.jsonl` where it runs, as an audit trail (no patient data on disk). `--trace` (or $SEMBLE_TRACE) escalates to the full request/response — headers + bodies — written to that file and echoed to stderr (DevTools-style) for debugging. Secrets (x-token, JWTs) are redacted; stdout stays clean data, so --trace is pipe-safe. Override dir: $SEMBLE_TRACE_DIR. Bodies clip to 4000 chars — use `--trace-full` (or $SEMBLE_TRACE_FULL) for whole payloads, or $SEMBLE_TRACE_MAX=<chars> for a custom cap.