CLI Reference

The Purple8 Hyper Graph (v0.72.0) CLI (purple8-hyper-graph) lets you manage databases, run the REST server, start the MCP bridge (125 MCP tools across 16 namespaces), and diagnose your environment without writing code.

Installation

pip install purple8-hyper-graph

After installation the purple8-hyper-graph binary is on your PATH.

Global flags

Flag	Description
--db PATH / -d PATH	Path to the graph database directory (default: ./purple8_data)
--verbose / -v	Show full tracebacks on error
--version / -V	Print the package version and exit
--help / -h	Show help text

---

init

Initialize a new graph database at the given path.

purple8-hyper-graph init ./my_graph
purple8-hyper-graph init ./my_graph --embedding-dim 768

Argument	Description
path	Directory to create the database in (falls back to --db)
--embedding-dim INT	Embedding vector dimension (default: 1536)

---

serve

Start the REST API server.

purple8-hyper-graph serve --port 8100
purple8-hyper-graph serve --host 0.0.0.0 --port 8100 --reload

Flag	Default	Description
--host TEXT	0.0.0.0	Interface to bind to
--port INT / -p INT	8100	TCP port
--reload	off	Enable auto-reload (development only)

You can also run the ASGI app directly (equivalent, useful when you need to pass uvicorn-specific flags like --workers): python -m purple8_graph.secure_server.

---

doctor

Check that all required and optional dependencies are installed and healthy.

purple8-hyper-graph doctor
purple8-hyper-graph doctor --url http://localhost:8100
purple8-hyper-graph doctor --json

Flag	Description
--url URL	Probe an API server's /health/live endpoint
--json	Emit results as JSON (useful in CI)

Exit codes: 0 = all checks pass, 1 = one or more failures.

Example output:

  ✓  Python version            3.12.x
  ✓  purple8_core              (Rust extension — BrickCoreStorage)
  ✓  hnswlib                   0.8.0
  ✓  numpy                     1.26.4
  ✓  pydantic                  2.12.5
  ✓  fastapi                   0.135.1
  ✓  uvicorn                   0.30.6
  ✓  pyjwt                     2.9.0
  ✓  cryptography              43.0.1
  ✓  [optional] openai         1.35.0
  ⚠  [optional] anthropic      not installed (optional)
  ✓  Server http://localhost:8100  HTTP 200

All checks passed (12 checks, 1 warning)

---

stats

Show statistics for the current graph database.

purple8-hyper-graph --db ./my_graph stats

---

node

node add

purple8-hyper-graph node add person_001 \
  --label Person \
  --property name=Alice \
  --property age=30

Argument	Description
node_id	Unique node identifier
--label / -l	Label to apply (repeatable)
--property / -p	Property as key=value (repeatable)

node get

purple8-hyper-graph node get person_001

node update

purple8-hyper-graph node update person_001 --property age=31

node delete

purple8-hyper-graph node delete person_001

node list

purple8-hyper-graph node list --label Person --limit 25

Flag	Description
--label / -l	Filter by label
--limit INT	Maximum results (default: 50)

---

edge

edge add

purple8-hyper-graph edge add knows_001 KNOWS person_001 person_002 --property since=2024

edge get

purple8-hyper-graph edge get knows_001

edge delete

purple8-hyper-graph edge delete knows_001

edge list

purple8-hyper-graph edge list --type KNOWS --from person_001 --limit 20

---

traverse

Traverse the graph from a starting node.

purple8-hyper-graph traverse person_001 --depth 3 --type KNOWS --direction outgoing

Flag	Default	Description
--depth / -d	2	Maximum traversal depth
--type / -t	all	Filter by edge type
--direction	outgoing	outgoing / incoming / both
--limit	50	Maximum results

---

export

Export graph data to a file.

purple8-hyper-graph export ./backup.json --format json
purple8-hyper-graph export ./backup.csv  --format csv
purple8-hyper-graph export ./graph.graphml --format graphml

---

import

Import graph data from a file.

purple8-hyper-graph import ./backup.json --format json
purple8-hyper-graph import ./backup.json --format json --clear

Flag	Description
--format / -f	json (default), csv, graphml
--clear	Wipe existing data before import

---

clear

Delete all nodes and edges from the database.

purple8-hyper-graph --db ./my_graph clear
purple8-hyper-graph --db ./my_graph clear --yes   # skip confirmation prompt

---

mcp-server

Start a local MCP stdio bridge to a running Purple8 REST API server — exposes all 125 MCP tools across 16 dot-namespaced namespaces (graph.*, rag.*, journey.*, schema.*, data.*, memory.*, registry.*, models.*, quantum.*, egress.*, feedback.*, scheduler.*, admin.*, evolution.*, sentinel.*, guardrails.*) to Claude Desktop, Claude Code, Cursor, and other MCP clients.

purple8-hyper-graph mcp-server --url http://localhost:8100 --api-key p8g_...
purple8-hyper-graph mcp-server --url http://localhost:8100 --username admin --password ...

Flag	Description
--url URL	Base URL of the running Purple8 REST API (required)
--api-key KEY	Long-lived API key (X-API-Key header) — mutually exclusive with --username
--username USER	Admin username for JWT login (use with --password) — mutually exclusive with --api-key
--password PASS	Admin password for JWT login (required when --username is set)
--timeout SECONDS	HTTP request timeout (default: 30)

See the MCP guide for the full tool catalog and Claude Desktop/Cursor connection instructions.

---

reset-password

Offline admin password reset / recovery — no SMTP required. Must be invoked via this console-script entry point (purple8-hyper-graph reset-password ...), not python -m: Nuitka-compiled commercial images do not support python -m for in-package modules.

purple8-hyper-graph reset-password --email admin@example.com --password newpass123
purple8-hyper-graph reset-password --email admin@example.com --create --username admin

Flag	Description
--email EMAIL	Email of the account to reset (or create with --create) (required)
--password PASSWORD	New password (omit to be prompted interactively)
--username USERNAME	Username to use when creating a new account with --create
--create	Create the account (bootstraps a super_admin) if it does not exist

---

KMS management

There is no kms CLI subcommand. Key inspection and rotation are exposed via the REST API instead (requires KMS_MANAGE permission):

curl -H "Authorization: Bearer $TOKEN" http://localhost:8100/admin/kms/keys
curl -H "Authorization: Bearer $TOKEN" http://localhost:8100/admin/kms/keys/{key_id}

See Encryption & KMS for the full KMS provider setup and rotation guide.