CLI Reference

# Graphiti CLI Commands Guide¶

Complete reference for GuardKit's Graphiti knowledge graph CLI commands.

Overview¶

GuardKit integrates with Graphiti to provide persistent knowledge across Claude Code sessions. The guardkit graphiti commands manage seeding, verification, and clearing of knowledge.

Commands¶

`guardkit graphiti seed`¶

Seeds system context into the Graphiti knowledge graph.

Usage:

guardkit graphiti seed
guardkit graphiti seed --force

Options: - --force, -f: Force re-seeding even if already seeded

What it does: - Seeds comprehensive GuardKit knowledge into Graphiti - Creates 15+ knowledge categories (product knowledge, command workflows, quality gates, etc.) - Adds metadata to all episodes for tracking and deduplication - Creates seeding marker file to prevent duplicate seeding

Example:

# First-time seeding
guardkit graphiti seed

# Force re-seed (e.g., after GuardKit upgrade)
guardkit graphiti seed --force

Knowledge categories seeded: - product_knowledge - What GuardKit is and its value proposition - command_workflows - How commands work together - quality_gate_phases - The 5-phase quality gate structure - technology_stack - Python CLI, Claude Code, SDK details - feature_build_architecture - Player-Coach pattern - architecture_decisions - Key design decisions - failure_patterns - Known failures and fixes - component_status - Complete/incomplete components - integration_points - Component connections - templates - Template metadata for search - agents - Agent capabilities and boundaries - patterns - Design pattern knowledge - rules - Rule applicability and examples - failed_approaches - Failed approaches with prevention guidance - quality_gate_configs - Quality gate threshold configurations

`guardkit graphiti status`¶

Shows Graphiti connection and seeding status.

Usage:

guardkit graphiti status

What it shows: - Graphiti enabled/disabled status - Neo4j connection details (URI, user, timeout) - Connection health check - Seeding status (seeded/not seeded, version)

Example output:

Graphiti Status

Enabled         Yes
Neo4j URI       bolt://localhost:7687
Neo4j User      neo4j
Timeout         30s

Connection: OK
Health: OK

Seeded: Yes (version 1.0.0)

`guardkit graphiti verify`¶

Verifies seeded knowledge with test queries.

Usage:

guardkit graphiti verify
guardkit graphiti verify --verbose

Options: - --verbose, -v: Show detailed query results

What it does: - Runs 5 test queries against different knowledge categories - Verifies that seeding was successful - Checks that semantic search is working

Example:

# Quick verification
guardkit graphiti verify

# Verbose output with results
guardkit graphiti verify --verbose

`guardkit graphiti clear`¶

Clears Graphiti knowledge graph data.

Usage:

# Clear ALL knowledge (requires --confirm)
guardkit graphiti clear --confirm

# Clear system-level knowledge only
guardkit graphiti clear --system-only --confirm

# Clear current project's knowledge only
guardkit graphiti clear --project-only --confirm

# Preview what would be deleted (no --confirm needed)
guardkit graphiti clear --dry-run

# Automation-friendly (skip prompts)
guardkit graphiti clear --confirm --force

Options: - --confirm: Required for actual deletion (safety check) - --system-only: Only clear system-level knowledge (templates, patterns, workflows) - --project-only: Only clear current project's knowledge - --dry-run: Show what would be deleted without deleting - --force, -f: Skip confirmation prompts (for automation)

Safety features: - Requires --confirm flag to prevent accidental deletion - Shows preview of what will be deleted before proceeding - --dry-run allows safe exploration - --system-only and --project-only are mutually exclusive

What it clears:

System Groups (cleared with --system-only or default): - guardkit_templates - Template metadata - guardkit_patterns - Design pattern knowledge - guardkit_workflows - Workflow definitions - product_knowledge - GuardKit product info - command_workflows - Command workflow knowledge - quality_gate_phases - Quality gate information - technology_stack - Technology stack details - feature_build_architecture - Feature-build patterns - And all other system-level groups

Project Groups (cleared with --project-only or default): - {project}__project_overview - Project-specific overview - {project}__project_architecture - Project architecture - {project}__feature_specs - Feature specifications - {project}__project_decisions - Project-specific decisions

Examples:

# Preview before clearing (safe)
guardkit graphiti clear --dry-run

# Clear everything after reviewing preview
guardkit graphiti clear --confirm

# Clear only system knowledge (preserve project context)
guardkit graphiti clear --system-only --confirm

# Clear only current project (preserve GuardKit system knowledge)
guardkit graphiti clear --project-only --confirm

# For CI/CD automation
guardkit graphiti clear --confirm --force

When to use: - After GuardKit upgrade: Clear system knowledge, then re-seed

guardkit graphiti clear --system-only --confirm
guardkit graphiti seed

Starting fresh on a project: Clear project knowledge

guardkit graphiti clear --project-only --confirm

Complete reset: Clear everything

guardkit graphiti clear --confirm
guardkit graphiti seed

Before testing: Ensure clean state

guardkit graphiti clear --dry-run  # Check what exists
guardkit graphiti clear --confirm  # Clear it

Output example:

Graphiti Knowledge Clear

Connecting to Neo4j at bolt://localhost:7687...
Connected to Graphiti

The following will be deleted:

System Groups:
  - product_knowledge
  - command_workflows
  - quality_gate_phases

Project Groups:
  - guardkit__project_overview
  - guardkit__feature_specs

Total groups: 5
Estimated episodes: 150

Clearing knowledge...

All knowledge cleared!
System groups cleared: 3
Project groups cleared: 2
Total episodes deleted: 150

`guardkit graphiti add-context`¶

Adds context from markdown files to the Graphiti knowledge graph.

Usage:

guardkit graphiti add-context <PATH> [OPTIONS]

Arguments: - PATH: File or directory to add (required)

Options: - --type TEXT: Force specific parser type (adr, feature-spec, project-overview, project-doc) - --force, -f: Overwrite existing context - --dry-run: Preview what would be added without actually adding - --pattern TEXT: Glob pattern for directories (default: **/*.md) - --verbose, -v: Show detailed processing output - --quiet, -q: Suppress non-error output

What it does: - Automatically detects document type (ADR, feature spec, project overview, etc.) - Extracts structured metadata from documents - Creates searchable episodes in Graphiti knowledge graph - Supports single files or bulk directory operations

Examples:

# Add a single Architecture Decision Record
guardkit graphiti add-context docs/architecture/ADR-001-use-graphiti.md

# Add all ADRs from directory
guardkit graphiti add-context docs/architecture/ --pattern "ADR-*.md"

# Add a feature specification
guardkit graphiti add-context docs/features/FEATURE-SPEC-authentication.md

# Preview what would be added (dry run)
guardkit graphiti add-context docs/ --dry-run

# Force specific parser type
guardkit graphiti add-context custom-doc.md --type adr

# Verbose output for debugging
guardkit graphiti add-context docs/ --verbose

# Quiet mode for automation
guardkit graphiti add-context docs/ --quiet

Supported document types: - ADR (Architecture Decision Records): ADR-*.md files or content with Status/Context/Decision sections - Feature Specs: FEATURE-SPEC-*.md files with YAML frontmatter - Project Overview: CLAUDE.md, README.md files - Project Docs: Any other markdown documentation

Output:

Graphiti Add Context

Connected to Graphiti

  ✓ docs/architecture/ADR-001.md (adr)
  ✓ docs/features/FEATURE-SPEC-auth.md (feature-spec)
  ✓ CLAUDE.md (project-overview)

Summary:
  Added 3 files, 8 episodes

When to use: - Initial setup: Add core project documentation to Graphiti - After creating docs: Add new ADRs, feature specs immediately - After updates: Use --force to update existing episodes - Bulk operations: Add all documentation from a directory

See also: - Graphiti Add Context Guide - Detailed command reference - Graphiti Parsers Guide - Parser types and detection - Context Addition Deep-Dive - Architecture details

`guardkit graphiti seed-adrs`¶

Seeds feature-build Architecture Decision Records (ADRs).

Usage:

guardkit graphiti seed-adrs
guardkit graphiti seed-adrs --force

Options: - --force, -f: Force re-seeding even if already seeded

What it seeds: - ADR-FB-001: Use SDK query() for task-work invocation - ADR-FB-002: Use FEAT-XXX paths in feature mode - ADR-FB-003: Pre-loop must invoke real task-work

When to use: - After running /feature-build for the first time - When upgrading feature-build implementation - When troubleshooting feature-build issues

Metadata in Episodes¶

All seeded episodes include a _metadata block for tracking and deduplication:

{
  "entity_type": "command",
  "name": "/task-work",
  "purpose": "Implement tasks through quality gates",
  "_metadata": {
    "source": "guardkit_seeding",
    "version": "1.0.0",
    "created_at": "2024-01-30T12:00:00Z",
    "updated_at": "2024-01-30T12:00:00Z",
    "source_hash": null,
    "entity_id": "command_task_work"
  }
}

Metadata fields: - source: Always "guardkit_seeding" for system context - version: Seeding version (e.g., "1.0.0") - created_at: ISO timestamp when episode was created - updated_at: ISO timestamp of last update - source_hash: Hash of source file (null for generated content) - entity_id: Unique identifier for deduplication

Benefits: - Deduplication: Prevent duplicate episodes across re-seeding - Version tracking: Know which seeding version created the episode - Provenance: Track where knowledge came from - Updates: Detect when content has changed

Configuration¶

Graphiti configuration is in ~/.guardkit/config.yaml:

graphiti:
  enabled: true
  neo4j_uri: bolt://localhost:7687
  neo4j_user: neo4j
  neo4j_password: password
  timeout: 30

Environment variables (override config file): - GRAPHITI_ENABLED: Set to false to disable - GRAPHITI_NEO4J_URI: Neo4j connection URI - GRAPHITI_NEO4J_USER: Neo4j username - GRAPHITI_NEO4J_PASSWORD: Neo4j password - GRAPHITI_TIMEOUT: Connection timeout in seconds

Workflow Examples¶

Initial Setup¶

# Check status
guardkit graphiti status

# Seed knowledge
guardkit graphiti seed

# Verify it worked
guardkit graphiti verify

After GuardKit Upgrade¶

# Clear old system knowledge
guardkit graphiti clear --system-only --confirm

# Seed new version
guardkit graphiti seed --force

# Verify
guardkit graphiti verify

Fresh Project Start¶

# Clear project-specific knowledge only
guardkit graphiti clear --project-only --confirm

# System knowledge is preserved, project starts fresh

Troubleshooting¶

# Check what's in the graph
guardkit graphiti clear --dry-run

# Check connection
guardkit graphiti status

# Verify seeded knowledge
guardkit graphiti verify --verbose

# Complete reset
guardkit graphiti clear --confirm
guardkit graphiti seed

Error Handling¶

All commands handle errors gracefully:

Connection failures: Show clear error message, exit cleanly
Disabled client: Skip operations, show warning
Partial failures: Continue with other operations, show warnings
Missing marker: Safe to re-seed or clear

Common issues:

"Graphiti not available": Check Neo4j is running

# Start Neo4j (Docker example)
docker run -d \
  -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:latest

"Connection refused": Check neo4j_uri in config
```
guardkit graphiti status
```
"Seeding marker missing": Run seed again
```
guardkit graphiti seed
```

Best Practices¶

Seed after installation
```
guardkit graphiti seed
```
Verify periodically
```
guardkit graphiti verify
```

Clear before major upgrades

guardkit graphiti clear --system-only --confirm
guardkit graphiti seed --force

Use --dry-run before clearing
```
guardkit graphiti clear --dry-run
```

Keep project knowledge across upgrades

# Only clear system knowledge
guardkit graphiti clear --system-only --confirm

CLI Reference

# Graphiti CLI Commands Guide¶

Overview¶

Commands¶

guardkit graphiti seed¶

guardkit graphiti status¶

guardkit graphiti verify¶

guardkit graphiti clear¶

guardkit graphiti add-context¶

guardkit graphiti seed-adrs¶

Metadata in Episodes¶

Configuration¶

Workflow Examples¶

Initial Setup¶

After GuardKit Upgrade¶

Fresh Project Start¶

Troubleshooting¶

Error Handling¶

Best Practices¶

See Also¶

`guardkit graphiti seed`¶

`guardkit graphiti status`¶

`guardkit graphiti verify`¶

`guardkit graphiti clear`¶

`guardkit graphiti add-context`¶

`guardkit graphiti seed-adrs`¶