Graffold CLI¶

Command-line interface for the Graffold Knowledge Graph Platform. Styled to match the graffold.com terminal preview — ASCII banner, brand colors (cyan / violet / emerald), and a graffold <resource> <command> [flags] structure.

Quick Start¶

# Just run it — prints the banner with live config detection
uv run python -m cli.cli

# Or after uv sync, use the entry point
graffold

Output:

 ██████  ██████   █████  ███████ ███████  ██████  ██      ██████
██       ██   ██ ██   ██ ██      ██      ██    ██ ██      ██   ██
██   ███ ██████  ███████ █████   █████   ██    ██ ██      ██   ██
██    ██ ██   ██ ██   ██ ██      ██      ██    ██ ██      ██   ██
 ██████  ██   ██ ██   ██ ██      ██       ██████  ███████ ██████
  v0.2.0  Turn anything into actionable knowledge

  Api           http://localhost:8000
  Neo4j         bolt://localhost:7687  (neo4j@neo4j)
  Redis         localhost:6379  (sessions + cache)
  Auth          enabled  (API_AUTH_TOKEN)
  Llm           bedrock  (default)

  Usage:  graffold <resource> <command> [flags]

  Resources:
    ingest        PubMed, bioRxiv, PMC, PDF ingestion
    enrich        CSV/Excel enrichment pipeline
    pipeline      Full automated KG creation
    query         Natural language graph queries
    consolidate   Entity & relationship merging
    embeddings    Vector embedding generation
    serve         Start the API server
    health        Check API / database / Redis status
    benchmark     Run query latency benchmarks

  Documentation:
    Quick Start   https://github.com/graffold/graffold-api/wiki/Quick-Start
    API Docs      http://localhost:8000/docs
    Frontend      http://localhost:5173
    GitHub        github.com/graffold/graffold-api

  Run with --help for all options

Configuration¶

Reads from .env (same file as the API):

Variable	Default	Description
`GRAFFOLD_API_URL`	`http://localhost:8000`	API base URL
`API_AUTH_TOKEN`	(empty)	Bearer token for authenticated endpoints
`NEO4J_URI`	`bolt://localhost:7687`	Shown in banner status block (works with Neo4j and Memgraph)
`NEO4J_DATABASE`	`neo4j`	Shown in banner status block
`REDIS_HOST`	`localhost`	Shown in banner status block

Commands¶

`graffold` (no args)¶

Prints the banner with auto-detected config from .env and environment.

`graffold serve`¶

Start the API server via granian.

graffold serve                        # localhost:8000
graffold serve --host 0.0.0.0 --port 9000 --reload

`graffold health`¶

Check API, database, LLM, and liveness status.

graffold health
# ✓ API        status=ok  version=0.2.0  uptime=479.11s
# ✓ database   ok  (0.26ms)
# ✓ llm        ok  (0.01ms)
# ✓ Liveness   alive

`graffold query`¶

Natural language query with mode and depth selection. Streams by default.

graffold query "What proteins are associated with heart disease?" -s sess_abc123
graffold query "Overview of IL-6" -s sess_abc123 --mode hybrid --depth deep
graffold query "List TP53 relationships" -s sess_abc123 --no-stream

`graffold ingest`¶

Submit an ingestion job and poll until completion.

graffold ingest -q "cardiovascular disease protein biomarker" --source pubmed -n 100
graffold ingest -q "protein biomarker" --source biorxiv -db olink1 --service bedrock

`graffold pipeline`¶

Run the full automated KG creation pipeline.

graffold pipeline --csv-dir data/csv --pubmed-queries data/queries.txt -db olink1
graffold pipeline --csv-dir data/csv -db olink1 --skip-pubmed
graffold pipeline --pubmed-queries data/queries.txt -db olink1 --skip-csv --skip-embeddings

`graffold enrich`¶

CSV/Excel enrichment.

graffold enrich -f data/proteins.csv -db olink1
graffold enrich -f data/ontology.csv -db olink1 --column-handlers "0:mondo-id,1:disease-name"

`graffold consolidate`¶

Entity and relationship merging.

graffold consolidate -db olink1                    # full (entities + relationships)
graffold consolidate -db olink1 --operation entities
graffold consolidate -db olink1 --operation relationships

`graffold embeddings`¶

Generate vector embeddings for semantic search.

graffold embeddings -db olink1 --service bedrock

`graffold benchmark`¶

Run query latency benchmarks against the API. Measures avg/p50/p95/p99 per query.

# Built-in test queries (5 queries × 5 iterations)
graffold benchmark -s sess_abc123

# Custom queries from file
graffold benchmark -s sess_abc123 -f data/test_queries.txt -n 10

# Specific mode/depth, save results
graffold benchmark -s sess_abc123 --mode hybrid --depth deep -n 20 -o results.json

Output:

Benchmarking 5 queries × 5 iterations
Session: sess_abc123  Mode: auto  Depth: balanced

  ✓ What proteins are associated with cardiovascular disease?
    avg=342ms  p50=320ms  p95=410ms  p99=410ms
  ✓ Which biomarkers are linked to kidney disease?
    avg=289ms  p50=275ms  p95=350ms  p99=350ms
  ...

┌──────────────────────────────────────────────────────────┐
│                   Benchmark Results                       │
├──────────────────────────────┬──────┬──────┬──────┬──────┤
│ Query                        │  Avg │  P50 │  P95 │  P99 │
├──────────────────────────────┼──────┼──────┼──────┼──────┤
│ What proteins are associated │342ms │320ms │410ms │410ms │
│ Which biomarkers are linked  │289ms │275ms │350ms │350ms │
└──────────────────────────────┴──────┴──────┴──────┴──────┘

JSON output (-o results.json):

{
  "version": "0.2.0",
  "results": [
    {
      "query": "What proteins are associated with cardiovascular disease?",
      "iterations": 5,
      "avg_ms": 342.1,
      "p50_ms": 320.4,
      "p95_ms": 410.2,
      "p99_ms": 410.2,
      "min_ms": 280.1,
      "max_ms": 410.2
    }
  ]
}

File Structure¶

cli/
├── cli.py          # The CLI — banner, click subcommands, API calls, benchmark
├── app.py          # Textual TUI (optional, run with graffold-tui)
├── styles.tcss     # TUI styles
├── screens/        # TUI screens (dashboard, sessions, ingest, query, health, costs)
└── widgets/        # TUI widgets (banner, nav)

Dependencies¶

Added to pyproject.toml:

click>=8.0.0 — CLI framework
rich>=13.0.0 — colored terminal output and tables
httpx>=0.28.0 — HTTP client for API calls

Entry points:

graffold → cli.cli:main (the CLI)
graffold-tui → cli.app:main (the Textual TUI, optional)

API Changes¶

The CLI required one new API endpoint:

GET /v1/sessions — Lists all active sessions. Added in api/v1/query/sessions.py.

Graffold CLI¶

Quick Start¶

Configuration¶

Commands¶

graffold (no args)¶

graffold serve¶

graffold health¶

graffold query¶

graffold ingest¶

graffold pipeline¶

graffold enrich¶

graffold consolidate¶

graffold embeddings¶

graffold benchmark¶