CLI Reference

The purple8-graph CLI lets you manage databases, run the REST server, and diagnose your environment without writing code.

Installation

pip install purple8-graph

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

Global flags

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

---

init

Initialize a new graph database at the given path.

purple8-graph init ./my_graph
purple8-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-graph serve
purple8-graph serve --host 0.0.0.0 --port 8010 --reload

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

---

doctor

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

purple8-graph doctor
purple8-graph doctor --url http://localhost:8010
purple8-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.11.9
  ✓  rocksdict                 0.3.24
  ✓  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:8010  HTTP 200

All checks passed (12 checks, 1 warning)

---

stats

Show statistics for the current graph database.

purple8-graph --db ./my_graph stats

---

node

node add

purple8-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-graph node get person_001

node update

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

node delete

purple8-graph node delete person_001

node list

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

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

---

edge

edge add

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

edge get

purple8-graph edge get knows_001

edge delete

purple8-graph edge delete knows_001

edge list

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

---

traverse

Traverse the graph from a starting node.

purple8-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-graph export ./backup.json --format json
purple8-graph export ./backup.csv  --format csv
purple8-graph export ./graph.graphml --format graphml

---

import

Import graph data from a file.

purple8-graph import ./backup.json --format json
purple8-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-graph --db ./my_graph clear
purple8-graph --db ./my_graph clear --yes   # skip confirmation prompt

---

kms

kms status

purple8-graph kms status
purple8-graph kms status --db ./data

Reports the active KMS provider, key ID, and how many values have been encrypted or are pending re-wrap after a rotation.

kms rotate

purple8-graph kms rotate --new-key-id "arn:aws:kms:us-east-1:...:key/mrk-NEW"

Initiates zero-downtime key rotation. Both old and new KEK versions must be active in your KMS until re-wrapping completes.