Account & status V3

The plugin's account state lives in three places: a few KB on your machine, a row on the server, the blockchain. Three commands and one endpoint surface everything you need to read. No web dashboard required today — the terminal is the dashboard.

Three ways to check

Pick whichever fits the moment:

• sibyl status — the terminal read. Combines local credentials, DB size, tier cache state, and a live server-side tier verification. The right default.
• sibyl health — provider self-check. Prints a JSON diagnostic dict for embedding in your own monitoring or pasting into a support thread.
• GET /api/plugin/access — raw server view. The endpoint sibyl status calls under the hood. Use directly if you're scripting tier checks from outside the SDK.

sibyl status

The 90% case. Combines everything a developer actually wants to see in one command:

Two parts of that output are worth knowing about.

Tier (server) vs Tier (local hint)

The local hint comes from your credentials.json. The server tier comes from a real-time call to /api/plugin/access. They should match. When they don't, sibyl status flags the drift in red. Possible causes:

• You upgraded in the browser but the CLI hasn't picked it up yet. Run sibyl status again and it rewrites the local hint automatically.
• You unstaked or your subscription expired. Server moved you to free; local file still says paid. The authoritative answer is the server. (Cap-checks always use the server view.)
• The credentials file was edited. The HMAC signature won't verify; server flags credentials_tamper_suspected and uses the database tier.

Tier cache freshness

For paid users, the SDK caches the server's "you're paid" answer for 7 days. Writes during that window never phone home; the cap stays off based on the cache. After 7 days, the next write triggers a refresh. The cache fresh until line in sibyl status tells you exactly when the next refresh fires.

Tier transitions

sibyl health

Boring on purpose. Returns a JSON dict describing the provider's view of itself. Useful for shell scripts, status pages, and support threads.

If anything's off, the corresponding field changes. "db_open": false, "server_reachable": false, "credentials": "missing", etc. The "ok" top-level field rolls them all up. A failing health check is the right thing to put in front of any "is it really working?" question.

/api/plugin/access (raw server view)

The endpoint sibyl status calls. Hit it directly if you're scripting tier checks from outside the Python SDK:

$ curl -s https://api.sibyllabs.org/api/plugin/access \
       -H "Authorization: Bearer $SIBYL_SESSION_TOKEN" | jq

What each field means

Cap-check telemetry (what we see, what we don't)

2026-05-16T23:55:21Z cap_check        tier=free  size=982KB  delta=+412B   ALLOW
2026-05-16T23:54:08Z cap_check        tier=free  size=982KB  delta=+1.1KB  ALLOW
2026-05-16T23:51:02Z cap_warning      tier=free  size=1.7MB  bucket=80%    PROMPT
2026-05-16T19:30:00Z tier_refresh     tier=free  source=db   ttl=7d        FRESH
2026-05-16T18:12:44Z upgrade_prompt   trigger=cap_warning           acknowledged

─────────────────────────────────────────────────────────────────────
telemetry stored per CLAUDE.md rule 43 · single source of truth
no entity body content · no journal text · no PII beyond account_id

We log size bucket transitions, cap-check ALLOW / DENY decisions, tier refreshes, and upgrade-prompt acknowledgements. We don't log entity body content, journal text, search queries, or anything else that would let us reconstruct what you've stored. The point of the telemetry is to know when the cap is firing in aggregate, not to learn what you're writing.

Common scenarios

"I just upgraded but my local CLI still says FREE"

Run sibyl status --refresh. The local hint sometimes lags the server by one cache cycle. If still wrong, check /api/plugin/access directly via curl — that's the authoritative source.

"I'm offline and my writes are getting rejected"

Paid users with a fresh cache (within the 7-day window) keep writing offline. If your cache expired while you were offline, you get a 14-day grace period before the SDK hard-caps at 2 MB. Beyond that, the SDK can't verify your paid status, so it falls back to free-tier rules. Reconnect once and the next cap-check refreshes the cache.

"I want to switch from email-only to wallet-bound"

Run sibyl init --add-wallet. Walks you through a SIWE bind against your existing account. The email stays bound; the wallet adds on. Required if you want to subscribe in USDC or qualify for the staker tier.

"I want to wipe and start fresh"

Delete the ~/.sibyl-memory/ directory and run sibyl init again. Your server-side account stays; you'll re-bind to it. If you also want to delete the server account, email [email protected] for a full account-deletion request (one-day turnaround, includes all telemetry purge).

Coming soon: account.sibyllabs.org

A logged-in web dashboard with the full read of everything above plus subscription history, receipt PDFs, audit timeline, and an embedded chat-bot with persistent memory of your past support interactions. Queued as a major project; build kicks off when one of three signals lands: first paid-customer receipt request, >5% renewal churn, or first multi-seat inquiry. The CLI today gets you 95% of what the dashboard will.