📘 CLI Usage Guide¶

Complete reference for the grai.build command-line interface.

🎯 Overview¶

The grai CLI provides commands for managing knowledge graph projects:

grai --help    # Show all commands
grai --version # Show version

📋 Commands¶

`grai init` - Initialize a New Project¶

Initialize a new grai.build project in the current directory (like git init or npm init).

# Create and enter your project directory first
mkdir my-graph-project
cd my-graph-project

# Initialize in current directory
grai init

Options:

--name, -n - Custom project name (default: directory name)
--force, -f - Overwrite existing files
path - Initialize in specific directory (default: .)

Examples:

# Initialize in current directory with default name
cd ~/projects/ecommerce
grai init
# Creates project named "ecommerce" (from directory name)

# Initialize with custom name
cd ~/projects/ecommerce
grai init --name my-custom-name
# Creates project named "my-custom-name"

# Initialize in different directory
grai init /path/to/project
# Creates project in /path/to/project

# Force overwrite existing files
grai init --force

What it creates:

my-graph-project/
├── grai.yml              # Project configuration
├── entities/             # Entity definitions
│   ├── customer.yml
│   └── product.yml
├── relations/            # Relation definitions
│   └── purchased.yml
├── target/               # Compiled output (empty initially)
│   └── neo4j/
└── README.md             # Project documentation

`grai validate` - Validate Project¶

Check entity and relation definitions for errors.

cd my-graph-project
grai validate

Options:

--strict, -s - Treat warnings as errors
--verbose, -v - Show detailed validation output
project_dir - Path to project directory (default: .)

Examples:

# Validate current project
grai validate

# Strict mode (warnings cause failure)
grai validate --strict

# Validate with details
grai validate --verbose

# Validate different project
grai validate /path/to/project

What it checks:

✅ Entity references exist
✅ Key mappings are valid
✅ No duplicate properties
✅ No circular dependencies
✅ Required fields present
✅ Valid data types

`grai build` - Compile to Cypher¶

Compile your project to Neo4j Cypher statements.

cd my-graph-project
grai build

Options:

--output, -o - Output directory (default: target/neo4j)
--filename, -f - Output filename (default: compiled.cypher)
--schema-only - Generate only schema (constraints/indexes)
--skip-validation - Skip validation before compiling
--verbose, -v - Show detailed build output
--full - Force full rebuild (ignore cache)
--no-cache - Don't update cache after build
project_dir - Path to project directory (default: .)

Examples:

# Basic build
grai build

# Custom output location
grai build --output ./output --filename schema.cypher

# Schema only (no data loading statements)
grai build --schema-only

# Skip validation (faster, but risky)
grai build --skip-validation

# Detailed output
grai build --verbose

# Force full rebuild (ignore incremental cache)
grai build --full

# Build without updating cache
grai build --no-cache

Output:

Creates target/neo4j/compiled.cypher containing:

Constraint definitions (UNIQUE keys)
Index definitions (performance)
Entity MERGE statements
Relation MERGE statements

`grai run` - Execute Against Neo4j¶

Build and execute Cypher against a Neo4j database.

By default, only creates the schema (constraints and indexes). Use --with-data to include data loading statements (requires CSV files).

cd my-graph-project
grai run --password mypassword

Options:

--uri, -u - Neo4j connection URI (default: bolt://localhost:7687)
--user - Username (default: neo4j)
--password, -p - Password (prompts if not provided)
--database, -d - Database name (default: neo4j)
--file, -f - Cypher file to execute (default: target/neo4j/compiled.cypher)
--schema-only - Create only schema (default: True)
--with-data - Include data loading statements (requires LOAD CSV context)
--load-csv - Load CSV data from data/ directory after creating schema
--dry-run - Show what would be executed without running
--skip-build - Skip building before execution
--verbose, -v - Show detailed execution output
project_dir - Path to project directory (default: .)

Examples:

# Create schema only (default, recommended for getting started)
grai run

# Create schema AND load CSV data in one command
grai run --load-csv --password secret

# Create schema with explicit flag
grai run --schema-only

# Include data loading statements (requires CSV files)
grai run --with-data

# Specify connection details
grai run --uri bolt://localhost:7687 --user neo4j --password secret

# Different database
grai run --database mygraph --password secret

# Execute specific Cypher file
grai run --file custom.cypher --password secret

# Dry run (see what would execute)
grai run --dry-run --password secret

# Skip rebuild (use existing compiled.cypher)
grai run --skip-build --password secret

# Verbose output (show database stats)
grai run --verbose --password secret

Remote Neo4j:

# Connect to remote Neo4j instance
grai run \
  --uri bolt://my-neo4j-server.com:7687 \
  --user neo4j \
  --password mypassword \
  --database production

`grai import` - Import from External Tools¶

Import entities and relations from external tools like dbt.

cd my-graph-project
grai import dbt --manifest ../my-dbt-project/target/manifest.json

Arguments:

source_type - Type of source to import from (currently only dbt supported)

Options:

--manifest, -m - Path to dbt manifest.json file (required for dbt imports)
--output, -o - Output directory for generated entity files (default: entities)
--include, -i - Comma-separated patterns to include (e.g., 'fct*,dim*')
--exclude, -e - Comma-separated patterns to exclude (e.g., 'stg*,tmp*')
--force, -f - Overwrite existing entity files

Examples:

# Import all dbt models
grai import dbt --manifest ../my-dbt-project/target/manifest.json

# Import only fact and dimension tables
grai import dbt --manifest target/manifest.json --include "fct_,dim_"

# Exclude staging models
grai import dbt --manifest target/manifest.json --exclude "stg_"

# Overwrite existing files
grai import dbt --manifest target/manifest.json --force

# Custom output directory
grai import dbt --manifest target/manifest.json --output my-entities/

What it does:

Parses dbt manifest.json file
Converts dbt models → grai.build entities
Preserves column types, descriptions, and metadata
Infers entity keys from dbt unique tests
Detects relationship tables (2+ foreign keys) and creates relations
Writes entity YAML files to the specified directory

See also: dbt Integration Guide for detailed workflow examples.

`grai load` - Load Data from Warehouse¶

Load entities or relations from your data warehouse (BigQuery, PostgreSQL, or Snowflake) into Neo4j.

cd my-graph-project
grai load customer

Arguments:

entity_or_relation - Name of entity or relation to load (required)

Options:

--profile - Profile name from ~/.grai/profiles.yml (default: from grai.yml or 'default')
--target - Target environment (dev, staging, prod, etc.)
--limit, -l - Limit number of rows to load (for testing)
--batch-size, -b - Batch size for loading (default: 5000)
--use-apoc - APOC usage mode: 'auto' (default), 'force', or 'never'
--where, -w - SQL WHERE clause for filtering (PostgreSQL/Snowflake)
--query, -q - Custom SQL query (overrides default table query)
--verbose, -v - Show detailed progress and statistics
--dry-run - Show what would be loaded without executing

Examples:

# Load customer entity (auto-detects warehouse from profile)
grai load customer

# Load PURCHASED relation
grai load PURCHASED

# Test with limited rows
grai load customer --limit 100

# Use specific profile
grai load customer --profile production --target prod

# Filter data (Postgres/Snowflake)
grai load customer --where "created_at > '2024-01-01'"

# Custom query (BigQuery)
grai load customer --query "SELECT * FROM analytics.customers WHERE region = 'US'"

# Verbose output
grai load customer --verbose

# Custom batch size
grai load customer --batch-size 10000

# Force APOC usage (fails if not available)
grai load customer --use-apoc force

# Never use APOC (always standard loading)
grai load customer --use-apoc never

# Dry run (preview what would be loaded)
grai load customer --dry-run --limit 10

Warehouse Auto-Detection:

The grai load command automatically detects your warehouse type from ~/.grai/profiles.yml:

# BigQuery example
default:
  target: dev
  outputs:
    dev:
      warehouse:
        type: bigquery
        method: oauth
        project: my-project
        dataset: analytics
      graph:
        type: neo4j
        uri: bolt://localhost:7687
        user: neo4j
        password: mypassword

Supported warehouse types:

bigquery - Google Cloud BigQuery
postgres - PostgreSQL (including Amazon RDS, Google Cloud SQL)
snowflake - Snowflake Data Warehouse

APOC Optimization:

When APOC plugin is available in Neo4j, loading is 2-3x faster:

# Check APOC availability in Neo4j Browser
RETURN apoc.version();

# Auto-detect and use if available (default)
grai load customer --use-apoc auto

# Force APOC (fails if not installed)
grai load customer --use-apoc force

# Never use APOC
grai load customer --use-apoc never

Progress Tracking:

grai load customer --verbose

# Output:
# ✅ Loaded profile: default (target: dev)
# 📦 Warehouse: BigQuery (project: my-project, dataset: analytics)
# 🔌 Neo4j: bolt://localhost:7687 (database: neo4j)
# 🚀 APOC detected: v5.12.0 - using optimized bulk loading
# 📊 Loading customer entity...
# ⏳ Extracting from BigQuery...
# 📦 Extracted 15,234 rows
# ⚡ Loading to Neo4j with APOC...
# [spinner] Loading batches... (3/4 batches complete)
# ✅ Loaded 15,234 nodes in 4.2s
# 📈 Throughput: 3,627 nodes/sec

See Data Loading Guide for detailed warehouse configuration.

`grai export` - Export Graph IR¶

Export project to Graph IR (Intermediate Representation) as JSON.

cd my-graph-project
grai export

Options:

--output, -o - Output file path (default: graph-ir.json)
--format, -f - Export format (currently only json)
--pretty/--compact - Pretty-print JSON (default: pretty)
--indent, -i - Indentation spaces (default: 2)
project_dir - Path to project directory (default: .)

Examples:

# Export to default file
grai export

# Custom output file
grai export --output schema.json

# Compact JSON
grai export --compact

# Custom indentation
grai export --indent 4

Output structure:

{
  "project": {
    "name": "my-graph",
    "version": "1.0.0"
  },
  "entities": [...],
  "relations": [...],
  "statistics": {
    "entity_count": 2,
    "relation_count": 1,
    "total_properties": 9
  }
}

`grai info` - Show Project Information¶

Display project statistics and structure.

cd my-graph-project
grai info

Options:

project_dir - Path to project directory (default: .)

Examples:

# Show current project info
grai info

# Show different project info
grai info /path/to/project

Output:

Project name and version
Entity count and details
Relation count and details
Property statistics
Source mappings

`grai cache` - Manage Build Cache¶

View or clear incremental build cache.

cd my-graph-project
grai cache --show

Options:

--clear, -c - Clear the build cache
--show, -s - Show cache contents
project_dir - Path to project directory (default: .)

Examples:

# Show cache info
grai cache --show

# Clear cache
grai cache --clear

# Both (show then clear)
grai cache --show --clear

What it shows:

Cached file hashes
Last build timestamp
Changed files since last build
Cache size

`grai lineage` - Analyze Lineage¶

Track entity relationships and calculate impact analysis.

cd my-graph-project
grai lineage

Options:

--entity, -e - Show lineage for specific entity
--relation, -r - Show lineage for specific relation
--impact, -i - Calculate impact analysis for entity
--visualize, -v - Generate visualization (mermaid or graphviz)
--output, -o - Output file for visualization
--focus, -f - Focus visualization on specific entity
project_dir - Path to project directory (default: .)

Examples:

# Show general lineage statistics
grai lineage

# Show entity lineage
grai lineage --entity customer

# Show relation lineage
grai lineage --relation PURCHASED

# Calculate impact of changing an entity
grai lineage --impact customer

# Generate Mermaid diagram
grai lineage --visualize mermaid --output lineage.mmd

# Generate Graphviz diagram
grai lineage --visualize graphviz --output lineage.dot

# Focus on specific entity
grai lineage --visualize mermaid --focus customer

Visualization formats:

Mermaid - Markdown-compatible diagrams
Graphviz - DOT format for Graphviz tools

`grai visualize` - Generate Interactive Visualization¶

Create interactive HTML visualization of the knowledge graph.

cd my-graph-project
grai visualize --open

Options:

--output, -o - Output HTML file (default: graph.html)
--format, -f - Visualization format: d3 or cytoscape (default: d3)
--title, -t - Custom title (default: project name)
--width, -w - Canvas width in pixels (default: 1200)
--height, -h - Canvas height in pixels (default: 800)
--open - Open in browser after generation
project_dir - Path to project directory (default: .)

Examples:

# D3.js force-directed graph
grai visualize --format d3 --open

# Cytoscape.js network
grai visualize --format cytoscape --open

# Custom dimensions
grai visualize --width 1600 --height 1000 --open

# Custom title
grai visualize --title "My Knowledge Graph" --open

# Save to specific file
grai visualize --output my-graph.html --open

Visualization features:

D3.js: Force-directed physics simulation, drag-and-drop nodes
Cytoscape.js: Hierarchical layout, professional network view
Interactive: Click nodes for details, zoom, pan
Self-contained: Single HTML file, no external dependencies

🔄 Common Workflows¶

Create New Project¶

# 1. Create directory
mkdir ~/projects/my-graph && cd ~/projects/my-graph

# 2. Initialize
grai init

# 3. Verify structure
ls -la

Develop Schema¶

# 1. Edit YAML files
vim entities/customer.yml

# 2. Validate
grai validate

# 3. Build
grai build

# 4. Review output
cat target/neo4j/compiled.cypher

# 5. Execute
grai run --password secret

Work from Any Directory¶

# Option 1: Navigate to project
cd ~/projects/my-graph
grai validate

# Option 2: Specify project path
grai validate ~/projects/my-graph
grai build ~/projects/my-graph

Incremental Builds¶

# First build (full)
grai build

# Edit a file
vim entities/customer.yml

# Next build (incremental - only changed files)
grai build

# Force full rebuild
grai build --full

Generate Documentation¶

# Export schema as JSON
grai export --output schema.json

# Generate lineage diagrams
grai lineage --visualize mermaid --output lineage.mmd
grai lineage --visualize graphviz --output lineage.dot

# Generate interactive visualization
grai visualize --format d3 --output graph-d3.html
grai visualize --format cytoscape --output graph-cytoscape.html

💡 Tips¶

1. Always initialize in an empty directory¶

# ✅ Good
mkdir my-graph && cd my-graph && grai init

# ❌ Bad
cd existing-project-with-files && grai init
# (Could overwrite files - use --force if intentional)

2. Use --dry-run for testing¶

# See what would be executed without actually running
grai run --dry-run --password secret

3. Use cache for faster builds¶

# Check what changed
grai cache --show

# Clear cache if needed
grai cache --clear

4. Validate before building¶

# Validation is automatic in build, but you can run it separately
grai validate && grai build

5. Use environment variables¶

# Set default Neo4j connection
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=secret

# Now you can omit these options
grai run

🆘 Getting Help¶

# General help
grai --help

# Command-specific help
grai init --help
grai validate --help
grai build --help
grai run --help
grai export --help
grai info --help
grai cache --help
grai lineage --help
grai visualize --help

GETTING_STARTED.md - Complete beginner's guide
NEO4J_SETUP.md - Neo4j installation and setup
PARSER.md - YAML schema reference
VALIDATOR.md - Validation rules
COMPILER.md - Cypher generation details
VISUALIZER.md - Visualization options
LINEAGE.md - Lineage tracking guide
CACHE.md - Incremental build system

📝 Note: This document reflects the current CLI implementation. Some features may be added or changed in future versions.

📘 CLI Usage Guide¶

🎯 Overview¶

📋 Commands¶

grai init - Initialize a New Project¶

grai validate - Validate Project¶

grai build - Compile to Cypher¶

grai run - Execute Against Neo4j¶

grai import - Import from External Tools¶

grai load - Load Data from Warehouse¶

grai export - Export Graph IR¶

grai info - Show Project Information¶

grai cache - Manage Build Cache¶

grai lineage - Analyze Lineage¶

grai visualize - Generate Interactive Visualization¶

🔄 Common Workflows¶

Create New Project¶

Develop Schema¶

Work from Any Directory¶

Incremental Builds¶

Generate Documentation¶

💡 Tips¶

1. Always initialize in an empty directory¶

2. Use --dry-run for testing¶

3. Use cache for faster builds¶

4. Validate before building¶

5. Use environment variables¶

🆘 Getting Help¶

📚 Related Documentation¶

`grai init` - Initialize a New Project¶

`grai validate` - Validate Project¶

`grai build` - Compile to Cypher¶

`grai run` - Execute Against Neo4j¶

`grai import` - Import from External Tools¶

`grai load` - Load Data from Warehouse¶

`grai export` - Export Graph IR¶

`grai info` - Show Project Information¶

`grai cache` - Manage Build Cache¶

`grai lineage` - Analyze Lineage¶

`grai visualize` - Generate Interactive Visualization¶