CLI reference V3
The sibyl command. Four subcommands cover the full surface: init, upgrade,
status, health. Pure stdlib HTTP. No requests, no httpx, no
background daemon. The wheel installs in seconds.
Four subcommands, one shared session model.
Common flags (every subcommand)
| Flag | Default | Meaning |
|---|---|---|
--credentials-dir <path> | ~/.sibyl-memory/ | Use a different credentials + DB directory. Useful for multiple accounts on one machine. |
--api-base <url> | https://api.sibyllabs.org | Override the API host. For staging or self-hosted setups. |
--json | false | Emit machine-readable JSON instead of styled terminal output. |
--quiet · -q | false | Suppress informational output. Errors still print to stderr. |
--no-color | false | Disable ANSI color. Useful for CI logs. |
--help · -h | — | Show subcommand help and exit. |
--version | — | Print CLI + SDK + Hermes versions and exit. |
Activate your account. Generates a one-time session UUID, opens the browser to
sibyllabs.org/plugin/activate?session=…, prints a 6-digit pairing code for the email path,
and polls /api/plugin/check every 3 seconds with a 10-minute timeout. On bind, writes
~/.sibyl-memory/credentials.json atomically at mode 0600.
| Flag | Effect |
|---|---|
--reset | Revoke the existing session token, generate a new one, walk through activation again. Memory data preserved. |
--add-wallet | Run a SIWE bind against an existing email-only account. Required before subscribing in USDC or staker-tier checks. |
--no-browser | Don't auto-open the browser. Useful for SSH sessions; copy the URL by hand. |
--timeout <sec> | How long to poll for bind. Default 600 (10 min). |
POST /email-bind or /bind
GET /check (poll)
2 · timeout
130 · ctrl-c
Lift the free-tier cap. Opens sibyllabs.org/plugin/upgrade?session=… with your existing
session token. Polls /api/plugin/access every 3 seconds with a 15-minute timeout. On a tier
change, refreshes the local credentials.json hint and clears tier_cache.json
so your next write picks up the new entitlement without an extra round trip. Both files are local
performance hints — the cap decision is always made server-side, and the credentials JSON is HMAC-signed
so a hand-edit fails the server-side verification. See
authentication · tamper-evidence.
| Flag | Effect |
|---|---|
--path stake | Pre-select the staker path on the upgrade page. Skips the path-picker. |
--path subscribe | Pre-select the USDC subscribe path. |
--path lifetime | Pre-select the lifetime payment path. |
--no-browser | Print the upgrade URL without opening the browser. Useful for SSH. |
--timeout <sec> | How long to poll for tier change. Default 900 (15 min). |
tier_cache.json (clear)
GET /pricing (page-side)
subscribe · 1 USDC tx
The 90% command. Combines local credentials, DB size, tier cache freshness, and a live server-side tier verification. Flags tier drift between local and server. The right default to put in your shell prompt or run before any "is it really working?" question.
| Flag | Effect |
|---|---|
--refresh | Force a server-side tier re-check, ignoring the local cache. Use after an upgrade if the CLI hasn't picked it up. |
--cap-only | Print one line with current size + cap + tier. For shell prompts. |
--json | Emit JSON. See /memory/account for the schema. |
tier_cache.json
memory.db (size only)
1 · tier drift
2 · no credentials
3 · server unreachable
Provider self-check. Wraps SibylMemoryProvider.health() and emits a JSON dict describing
version, schema, DB state, credentials state, and server reachability. Useful for shell scripts, status
pages, and support threads.
| Flag | Effect |
|---|---|
--exit-code-mode | Emit a single OK/FAIL line and use the exit code as the signal. For shell if blocks. |
--no-network | Skip the server reachability probe. Useful when offline. |
memory.db (open test)
1 · partial degradation
2 · critical failure
Environment variables
Every flag also accepts an environment-variable override. Useful for CI, container deploys, or staging tests.
| Variable | Default | What it overrides |
|---|---|---|
SIBYL_API_BASE | https://api.sibyllabs.org | --api-base |
SIBYL_ACTIVATE_BASE | https://sibyllabs.org/plugin/activate | activation URL host |
SIBYL_UPGRADE_BASE | https://sibyllabs.org/plugin/upgrade | upgrade URL host |
SIBYL_CREDENTIALS_DIR | ~/.sibyl-memory/ | --credentials-dir |
SIBYL_QUIET | 0 | --quiet |
NO_COLOR | — | --no-color (per the NO_COLOR standard) |
Exit codes (full reference)
| Code | Meaning | Used by |
|---|---|---|
0 | Success | all |
1 | Soft failure / tier drift / partial degradation | status, health |
2 | Hard failure / timeout / no credentials | all |
3 | Server unreachable | status |
4 | HMAC verification failed (tamper-evidence triggered) | status |
130 | Interrupted (Ctrl-C) | all |
Scripting patterns
Wait until upgraded before continuing
#!/usr/bin/env bash
while ! sibyl status --cap-only | grep -q "tier=SYNC"; do sleep 3; done
echo "ready"Block deploy if memory is degraded
#!/usr/bin/env bash
sibyl health --exit-code-mode || { echo "memory degraded · aborting deploy"; exit 1; }Print cap usage in your shell prompt
# bash/zsh
PS1='$(sibyl status --cap-only --no-color 2>/dev/null | cut -c1-22) \w $ 'Sources
The CLI is implemented at packages/sibyl-memory-cli/src/sibyl_memory_cli/cli.py in the open
source tree. Pure stdlib — urllib only, no requests, no httpx. The wheel
is roughly 10 KB. Full changelog at packages/sibyl-memory-cli/CHANGELOG.md.