Graph databases,
in your terminal.

relate is a CLI for linting and parsing Cypher files, running parameterized queries against Neo4j, and exposing graph operations to AI agents via MCP.

v0.1.0 · releases

$ curl -sSfL https://cli.relateby.dev/install.sh | bash

Installs to ~/.local/bin. Apple Silicon and Intel both supported.

Manually downloaded binary blocked by Gatekeeper? Run: xattr -d com.apple.quarantine /path/to/relate

$ curl -sSfL https://cli.relateby.dev/install.sh | bash

Installs to ~/.local/bin. x86_64 and aarch64 both supported.

> powershell -c "irm https://cli.relateby.dev/install.ps1 | iex"

Installs to %LOCALAPPDATA%\Programs\relate.

$ brew install relateby/tap/relate

Upgrade with brew upgrade relate. Tap: relateby/homebrew-tap.

$ npm i -g @relateby/cli

Works with npm, pnpm, Bun, and --ignore-scripts CI environments.

$ cargo install relate

Compiles from source. Requires Rust 1.85+.

Quickstart

Install relate

Use any install method above. Verify with:

relate --version

Lint a Cypher file

Point relate lint at any .cypher file to get ariadne-style diagnostics:

relate lint query.cypher

Connect to Neo4j

Set credentials via environment variables or flags:

export NEO4J_PASSWORD=secret

Run a query

Execute parameterized Cypher and get results as a table:

relate query "MATCH (n) RETURN n LIMIT 5"

Commands

# Validate .cypher and .gram files
relate lint schema.cypher
relate lint --json queries/

# Exit codes: 0 = valid, 1 = errors, 2 = warnings

# Print the syntax tree of a Cypher or Gram file
relate parse schema.gram
relate parse --json query.cypher

# Run a Cypher query (credentials from env or flags)
relate query "MATCH (n:Person) RETURN n.name LIMIT 10"

# Named parameters
relate query --param name=Alice \
  "MATCH (n:Person {name: \$name}) RETURN n"

# Run a .cypher file from your query library
relate query find-person.cypher --param name=Alice

# Batch-execute a Cypher template against CSV rows
relate query create-person.cypher \
  --apply people.csv

# Also supports JSON arrays and JSONL
relate query create-node.cypher --apply nodes.jsonl

# Control transaction batch size
relate query load.cypher --apply data.csv --batch-size 500

# Start an MCP stdio server exposing relate commands
# Add to your AI agent's MCP config:
{
  "mcpServers": {
    "relate": {
      "command": "relate",
      "args": ["mcp"]
    }
  }
}

Agent Skills

relate ships with embedded skill bundles that teach AI coding agents how to use it — no extra configuration needed.

Claude Code

Install the relate skill with npx skills install relate or add it to your project's .claude/ directory.

Cursor / Windsurf

Place skills/relate/SKILL.md in your .cursorrules or agent context. Cursor picks it up automatically.

Copilot / Other

Skills follow the agentskills.io convention. Any agent that supports skill discovery works.

npx skills install relate

All install methods

Method	Platforms	Command
Shell script	macOS, Linux	`curl -sSfL https://cli.relateby.dev/install.sh \| bash`
PowerShell	Windows	`powershell -c "irm https://cli.relateby.dev/install.ps1 \| iex"`
Homebrew	macOS	`brew install relateby/tap/relate`
npm	All	`npm i -g @relateby/cli`
cargo	All (source)	`cargo install relate`
GitHub Releases	All (manual)	download archive

Graph databases,in your terminal.