CLI Quickstart

@phosra/cli is the fastest path to a green setup check. It wires automatically to the production sandbox — the stable, partner-facing testing endpoint with 16 seeded trust-list entries, a pre-seeded child policy, and zero new backend required. No config needed out of the box.

Install

npm install -g @phosra/cli

Verify installation:

phosra --version
# 0.2.0

Step 1 — `phosra init`

Scaffold a .phosra.env in your current directory. Pass --role provider for a parental-controls integration or --role platform for a content-app integration.

phosra init --role provider

Output:

  Phosra — init

  ✔  Wrote .phosra.env (role: provider)

  Next: run phosra doctor to verify the setup end-to-end.

The written .phosra.env is wired to the production sandbox — the stable testing endpoint — with the shared did:ocss:household-acme parent persona (a deterministic test key, safe for sandbox use). Add .phosra.env to your .gitignore — it contains a test seed. Config keys written:

Key	Value	Notes
`PHOSRA_CENSUS_URL`	`https://phosra-api-sandbox-production.up.railway.app`	Production sandbox census — the stable testing endpoint
`PHOSRA_TRUST_ROOT_X`	`CMHWy3vUAiEcYDdE_bDvkRuEqwxkklS0tV-TYHJTlWU`	Root public key X (base64url) — anchors trust-list verification
`PHOSRA_HOUSEHOLD_SEED`	`aG91c2Vob2xkLWFjbWUB...`	household-acme Ed25519 seed (deterministic test key)
`SANDBOX_MIA_POLICY_ID`	`b011c1e5-0000-4000-8000-000000000b01`	Pre-seeded test child policy
`SANDBOX_MIA_CHILD_ID`	`a11ce0fa-0000-4000-8000-0000000000a1`	Pre-seeded Mia child ref
`PHOSRA_TEST_KEYS`	`1`	Allows deterministic test-key derivation (sandbox only)
`PHOSRA_ROLE`	`provider`	Your integration role

https://phosra-api-sandbox-production.up.railway.app is the one canonical sandbox host — the stable, partner-facing testing endpoint every Phosra doc, example, and SDK default points at (why one host). Phosra runs a separate internal pre-release census for its own integration testing; it is not a partner surface and is deliberately never named in these docs. Point at the canonical host and stay there. To override for the live accredited network (real production traffic), replace PHOSRA_CENSUS_URL, PHOSRA_TRUST_ROOT_X, PHOSRA_HOUSEHOLD_SEED, and set PHOSRA_TEST_KEYS=0. Two different credentials, two different paths — don’t conflate them:

Your phosra_ management/API key is fully self-serve — sign up and mint it yourself, including phosra_live_ keys, with no email to anyone. See Create your account & get keys.
Live accredited census access (the real PHOSRA_CENSUS_URL + PHOSRA_TRUST_ROOT_X for production enforcement traffic, plus a production Trust List entry) is gated on OCSS accreditation, an external governance step — apply here. The sandbox above needs neither.

Step 2 — `phosra doctor`

Verify the full setup end-to-end. Runs five checks in order, exits 0 if all pass.

phosra doctor

Sample output (all green):

  Phosra doctor

  ✔ census_reachable      https://phosra-api-sandbox-production.up.railway.app
  ✔ trust_list_verified   16 entries, serial 1
  ✔ caps_verified         ocss_version 1.0.0, 123 rules, serial 4
  ✔ version_negotiates    agreed 1.0
  ✔ sandbox_round_trip    consent 201, rule 201, 16 trust-list entries — key verified vs trust-list

  5 passed · 0 failed

What each check does

Check	What it verifies
`census_reachable`	`GET /health` → 200 from the configured census URL
`trust_list_verified`	`GET /.well-known/ocss/trust-list` → parses the signed document and verifies the Ed25519 root signature against `PHOSRA_TRUST_ROOT_X`
`caps_verified`	`GET /.well-known/ocss/capabilities` → verifies the root signature; warns (non-fatal) if the endpoint is 404
`version_negotiates`	Calls `negotiate(CLIENT_VERSIONS, server.supported)` — confirms client and server share a common OCSS spec major version
`sandbox_round_trip`	Full §8.3.2 + §8.3.1 write cycle: fetches the trust list, extracts the router P-256 payload key, seals a `consent_attestation` envelope, POSTs to `/api/v1/webhooks/inbound/app-store` (→ 201), then POSTs `addictive_pattern_block` to `/api/v1/policies/{mia_policy_id}/rules` (→ 201)

Machine-readable output (for CI)

phosra doctor --json

Returns a JSON object:

{
  "ok": true,
  "checks": [
    { "name": "census_reachable",     "status": "pass", "message": "https://..." },
    { "name": "trust_list_verified",  "status": "pass", "message": "16 entries, serial 1" },
    { "name": "caps_verified",        "status": "pass", "message": "ocss_version 1.0.0, 123 rules, serial 4" },
    { "name": "version_negotiates",   "status": "pass", "message": "agreed 1.0" },
    { "name": "sandbox_round_trip",   "status": "pass", "message": "consent 201, rule 201, 16 trust-list entries" }
  ]
}

Exits 1 on any "status": "fail". "warn" is non-fatal (e.g. caps doc not yet published on the target census).

Step 3 — `phosra caps`

Fetch, verify, and pretty-print the capabilities document — the self-describing 123-rule catalog that the census publishes and signs.

phosra caps

Sample output:

  Phosra caps

  ✔  Verified to root  (CMHWy3vUAiEc...)

  OCSS version:   1.0.0
  Serial:         4
  Not after:      2027-06-01T00:00:00Z
  Version range:  1.0

  Rule categories (123):

    ANCHORED
      · addictive_pattern_block
      · age_appropriate_profile_mode
      · ai_chatbot_tier_gate
      · content_rating
      · ncii_takedown
      · parental_consent_gate
      · screen_time_report
      · ...

    PROVISIONAL
      · ...

phosra caps --json outputs the full structured document for downstream tooling.

Additional commands

`phosra register` (cold-party self-registration — sandbox)

The quickstart above uses the shared did:ocss:household-acme test persona. To onboard your own identity, phosra register generates a fresh Ed25519 DID, self-registers it on the sandbox census as a provisional Trust List entry, and proves a green verifiable round-trip — no pre-existing credential, no email. This is the CLI form of the self-register documented in the Provider quickstart (POST /api/v1/advisors/self-register).

phosra register --slug acme-controls --roles editor
# PASS — registered DID: did:ocss:acme-controls
#   trust tier: provisional
#   census:     https://phosra-api-sandbox-production.up.railway.app
#   env file:   .phosra.env
# GREEN — your own DID completed a verifiable round-trip

Sandbox only — the census rejects self-registration in production; the production Trust List is populated through OCSS accreditation. Writes PHOSRA_DID + your seed into .phosra.env (add it to .gitignore).

`phosra link write` (provider)

Write a signed rule directive via @phosra/link. Requires PHOSRA_DATABASE_URL for the grant store and an active grant ID from the connect ceremony.

phosra link write addictive_pattern_block \
  --grant-id <grant-id> \
  --child-ref child:a11ce0fa-0000-4000-8000-0000000000a1 \
  --decision block

`phosra gatekeeper check` (platform)

Refresh the enforcement profile and run isAllowed() for a rule category. Requires PHOSRA_ENDPOINT_ID.

phosra gatekeeper check addictive_pattern_block \
  --endpoint-id <endpoint-id> \
  --confirm applied

--confirm applied|degraded|refused emits a §8.3.8 enforcement-confirmation receipt.

Config priority

Config resolves in this order — higher priority wins:

Environment variables (e.g. PHOSRA_CENSUS_URL=...)
.phosra.env file in the current working directory
Baked-in production sandbox defaults (the values phosra init writes)

Override any single value without touching the file — e.g. run phosra doctor against an explicit census URL (still the canonical sandbox host; shown here only to demonstrate the override precedence):

PHOSRA_CENSUS_URL=https://phosra-api-sandbox-production.up.railway.app \
  PHOSRA_TRUST_ROOT_X=CMHWy3vUAiEcYDdE_bDvkRuEqwxkklS0tV-TYHJTlWU phosra doctor

Troubleshooting

Symptom	Cause	Fix
`census_reachable: FAIL — network error`	Wrong URL or no network	Check `PHOSRA_CENSUS_URL` in `.phosra.env`
`trust_list_verified: FAIL — signature verify`	`PHOSRA_TRUST_ROOT_X` doesn’t match this census’s root key	Get the correct root X from Phosra or use `phosra init` to reset to sandbox defaults
`sandbox_round_trip: FAIL — 401`	Household seed does not match the trust-list key for `did:ocss:household-acme`	`phosra init --force` to reset the seed, or contact developers@phosra.com
`caps_verified: WARN — 404`	This census hasn’t published its capabilities doc yet	Non-fatal — `phosra doctor` still passes overall; `phosra caps` will fail-exit

Provider quickstart — @phosra/link connect ceremony and rule writes
Platform quickstart — @phosra/gatekeeper profile read and local enforcement
Billing — what triggers an invoice

Get Started

Concepts

Guides

Cookbook

Partner Integration

Phosra Link (secret-free)

OCSS Conformance

Platform

Install

Step 1 — `phosra init`

Step 2 — `phosra doctor`

What each check does

Machine-readable output (for CI)

Step 3 — `phosra caps`

Additional commands

`phosra register` (cold-party self-registration — sandbox)

`phosra link write` (provider)

`phosra gatekeeper check` (platform)

Config priority

Troubleshooting

Next

​Install

​Step 1 — phosra init

​Step 2 — phosra doctor

​What each check does

​Machine-readable output (for CI)

​Step 3 — phosra caps

​Additional commands

​phosra register (cold-party self-registration — sandbox)

​phosra link write (provider)

​phosra gatekeeper check (platform)

​Config priority

​Troubleshooting

​Next

Install

Step 1 — `phosra init`

Step 2 — `phosra doctor`

What each check does

Machine-readable output (for CI)

Step 3 — `phosra caps`

Additional commands

`phosra register` (cold-party self-registration — sandbox)

`phosra link write` (provider)

`phosra gatekeeper check` (platform)

Config priority

Troubleshooting

Next