API Reference and CLI Manual

Complete reference for Geode CLI commands and GQL language surface.

CLI Overview

Geode ships a unified geode binary. Compatibility symlinks (geoded, geodec) are provided for legacy workflows.

CommandPurposeUsage
geode serveServer daemongeode serve --listen 0.0.0.0:3141
geode queryClient CLIgeode query "MATCH (n) RETURN n" --server 127.0.0.1:3141
geode shell / gqlInteractive REPLgeode shell

Server Commands (geode serve)

Start Server 

# Default (localhost:3141)
geode serve

# Custom listen address
geode serve --listen 0.0.0.0:3141

# With configuration file
geode serve --config /etc/geode/geode.yaml

# With TLS certificates
geode serve \
  --cert /etc/geode/certs/server-cert.pem \
  --key /etc/geode/certs/server-key.pem

# With data directory
geode serve --data-dir /var/lib/geode

Server Flags

FlagDescriptionDefault
--listen <addr>Listen address (host:port)127.0.0.1:3141
--config <file>Configuration file path-
--data-dir <dir>Data directory./geode-data
--cert <file>TLS certificate pathAuto-generated
--key <file>TLS key pathAuto-generated
--versionShow version-
--helpShow help-

Client Commands (geode query)

Execute Query 

# Single query
geode query "RETURN 1 AS x" --server 127.0.0.1:3141

# Query from file
geode query -f query.gql --server 127.0.0.1:3141

# With output format
geode query --format json "MATCH (n) RETURN n LIMIT 10" --server 127.0.0.1:3141
geode query --format txt "MATCH (n) RETURN n LIMIT 10" --server 127.0.0.1:3141

# Show execution time
geode query --timing "MATCH (p:Person) RETURN p.name" --server 127.0.0.1:3141

# Connect to remote server
geode query "MATCH (n) RETURN n" --server geode.example.com:3141

Client Flags

FlagDescriptionDefault
-f, --file <path>Read query from file-
--format <fmt>Output format (txt|json)txt
--timingShow execution timefalse
--timeout <seconds>Query timeout in seconds (increased from 10s to accommodate QUIC handshake latency in Docker/CI environments)30
--server <addr:port>Server address127.0.0.1:3141
--helpShow help-

Interactive Shell (geode shell)

Start REPL 

# Start shell
geode shell

# Or alternative entrypoint
gql

Meta Commands

From REPL_USAGE.md:

CommandDescriptionExample
\connect <uri>Connect to server\connect quic://localhost:3141
\beginStart transaction\begin
\commitCommit transaction\commit
\rollbackRollback transaction\rollback
\format <fmt>Set output format\format json
\timing on|offToggle execution timing\timing on
\helpShow help\help
\quitExit shell\quit

Shell Example Session 

-- Connect
\connect quic://localhost:3141

-- Set format
\format json

-- Enable timing
\timing on

-- Run query
MATCH (p:Person) RETURN p.name;

-- Start transaction
\begin

CREATE (:Person {name: "Alice", age: 30});

-- Commit
\commit

-- Exit
\quit

Admin and Ops Commands

Backup 

# Local backup
geode backup --output /backups/geode-$(date +%Y%m%d).tar.gz

# S3 backup
geode backup --dest s3://my-bucket/backups/geode-$(date +%Y%m%d).tar.gz

# With credentials
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... \
geode backup --dest s3://my-bucket/backups/backup.tar.gz

Restore 

# Restore from local
geode restore \
  --input /backups/geode-20240115.tar.gz \
  --data-dir /var/lib/geode

# Restore from S3
geode restore \
  --source s3://my-bucket/backups/geode-20240115.tar.gz \
  --data-dir /var/lib/geode

# Point-in-time recovery
geode restore \
  --source s3://my-bucket/backups/geode-20240115.tar.gz \
  --wal-dir /var/lib/geode/wal \
  --until "2024-01-15T14:30:00Z"

GQL Language Reference

Keywords

From API_REFERENCE_GENERATED.md, key GQL keywords:

Query Keywords:

  • MATCH - Pattern matching
  • WHERE - Filter predicates
  • RETURN - Projection
  • WITH - Pipeline chaining
  • ORDER BY - Sorting
  • LIMIT - Limit results
  • OFFSET - Skip results
  • DISTINCT - Remove duplicates

Write Keywords:

  • CREATE - Create nodes/relationships
  • DELETE - Delete nodes/relationships
  • DETACH DELETE - Delete node and relationships
  • SET - Update properties
  • MERGE - Upsert pattern
  • ON CREATE - Merge onCreate clause
  • ON MATCH - Merge onMatch clause

Transaction Keywords:

  • START TRANSACTION - Begin transaction
  • COMMIT - Commit changes
  • ROLLBACK - Rollback changes
  • SAVEPOINT - Create savepoint (extension)
  • ROLLBACK TO SAVEPOINT - Partial rollback (extension)

Set Operations:

  • UNION - Combine results (remove duplicates)
  • UNION ALL - Combine results (keep duplicates)
  • INTERSECT - Common results
  • EXCEPT - Set difference

Graph Operations:

  • CREATE GRAPH - Create graph
  • USE - Select graph
  • DROP GRAPH - Delete graph

Built-in Functions

Aggregation Functions
FunctionDescriptionExample
COUNT()Count rowsRETURN COUNT(p)
SUM()Sum valuesRETURN SUM(p.age)
AVG()Average valuesRETURN AVG(p.age)
MIN()Minimum valueRETURN MIN(p.age)
MAX()Maximum valueRETURN MAX(p.age)
String Functions
FunctionDescriptionExample
upper()UppercaseRETURN upper("hello") → "HELLO"
lower()LowercaseRETURN lower("HELLO") → "hello"
substring()Extract substringRETURN substring("hello", 0, 3) → "hel"
length()String lengthRETURN length("hello") → 5
Temporal Functions
FunctionDescriptionExample
timestamp()Current timestampRETURN timestamp()
date()Create dateRETURN date('2024-01-15')
time()Create timeRETURN time('14:30:00')
Type Conversion
FunctionDescriptionExample
toInteger()Convert to integerRETURN toInteger("42") → 42
toFloat()Convert to floatRETURN toFloat("3.14") → 3.14
toString()Convert to stringRETURN toString(42) → "42"
toBoolean()Convert to booleanRETURN toBoolean("true") → true
Vector Functions
FunctionDescriptionExample
vector_distance_l2()Euclidean distanceRETURN vector_distance_l2($a, $b)
vector_distance_cosine()Cosine distanceRETURN vector_distance_cosine($a, $b)
vector_distance_dot()Dot productRETURN vector_distance_dot($a, $b)

Data Types

From TYPES_AND_FUNCTIONS.md:

Core Types:

  • Null - Null value
  • Boolean - true/false
  • Integer - Signed integer (Int8/16/32/64)
  • Float - Floating point (Float32/64)
  • String - UTF-8 text
  • Decimal - Arbitrary precision decimal

Advanced Types:

  • Date - Calendar date
  • Time - Time of day
  • Timestamp - Date + time with timezone
  • Interval - Duration
  • JSON / JSONB - JSON data
  • Bytea - Binary data
  • VectorF32 / VectorI32 - Vector embeddings
  • LatLon / GeoPoint - Geographic coordinates
  • IpAddr / Subnet / MacAddr - Network addresses
  • UUID - Universally unique identifier
  • Hash - Cryptographic hash

See Data Model and Types for details.

Procedures

From API_REFERENCE_GENERATED.md:

Graph Algorithms:

  • graph.pageRank() - PageRank centrality
  • graph.betweenness() - Betweenness centrality
  • graph.closeness() - Closeness centrality
  • graph.louvain() - Community detection
  • graph.labelPropagation() - Label propagation
  • graph.node2vec() - Node2Vec embeddings
  • graph.graphSAGE() - GraphSAGE embeddings
  • graph.deepWalk() - DeepWalk embeddings

See Graph Algorithms for usage.

Next Steps