> ## Documentation Index > Fetch the complete documentation index at: https://docs.phosra.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI Quickstart > The fastest path to a signed round-trip: phosra init scaffolds a config, phosra doctor verifies census reachability, trust-list root signature, spec-version negotiation, and a full §8.3.2+§8.3.1 sandbox write — all in under two minutes with zero provisioning. `@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 ```bash theme={null} npm install -g @phosra/cli ``` Verify installation: ```bash theme={null} 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. ```bash theme={null} 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](/ocss/status)). 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](/platform/create-account). * **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](/integration/production-accreditation). 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. ```bash theme={null} 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) ```bash theme={null} phosra doctor --json ``` Returns a JSON object: ```json theme={null} { "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. ```bash theme={null} 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](/integration/provider) (`POST /api/v1/advisors/self-register`). ```bash theme={null} 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](/integration/production-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. ```bash theme={null} phosra link write addictive_pattern_block \ --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`. ```bash theme={null} phosra gatekeeper check addictive_pattern_block \ --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: 1. Environment variables (e.g. `PHOSRA_CENSUS_URL=...`) 2. `.phosra.env` file in the current working directory 3. 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): ```bash theme={null} 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](mailto: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 | *** ## Next * [Provider quickstart](/integration/provider) — `@phosra/link` connect ceremony and rule writes * [Platform quickstart](/integration/platform) — `@phosra/gatekeeper` profile read and local enforcement * [Billing](/integration/billing) — what triggers an invoice