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:

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.

There is no public production OCSS census configuration to substitute today. Keep CLI census evaluation on the documented sandbox; hosted decision routing and a production receipt rail remain roadmap.

The sandbox above uses synthetic identities and test keys. It does not confer accreditation. Production credentials and routing are not a self-serve CLI switch.

• Teams with a concrete workflow can apply for the design-partner beta; participation does not provide a production Trust List entry or certification.

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

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 — self-registration creates a synthetic test identity, not a production Trust List entry. Writes PHOSRA_DID + your seed into .phosra.env (add it to .gitignore). See the production roadmap for the current boundary.

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:

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):

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

Troubleshooting

Next

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