Crystal CLI Reference¶

crystal-cli is a command-line client for interacting with a running Crystal Graph Engine server.

Installation¶

go build -o crystal-cli ./cmd/crystal-cli

Or from Docker:

docker cp crystal:/app/crystal-cli ./crystal-cli

Configuration¶

Both settings come from the environment:

export CRYSTAL_URL=http://localhost:7540
export CRYSTAL_TOKEN=<your token>

CRYSTAL_URL defaults to http://localhost:7540 if not set.

CRYSTAL_TOKEN is the bearer token the server expects. Authentication is on by default, so without it every command fails with 401 unauthorized. It is read from the environment rather than taken as a flag so the credential stays out of your shell history and out of the process listing.

A token with read scope is enough for the query and traversal commands; the create, update and delete commands need write. See the Deployment Guide.

Property Syntax¶

Properties are passed as key=value pairs after the command arguments.

key=value sets a string property
key:=value sets a JSON-typed property (numbers, booleans, arrays, objects)

crystal-cli vertex create Person name=Alice age:=30 active:=true
crystal-cli vertex create Config tags:='["web","prod"]'

Commands¶

Server¶

crystal-cli health                     # health check
crystal-cli stats                      # graph statistics
crystal-cli flush                      # flush to disk
crystal-cli version                    # CLI version

Vertices¶

List vertices:

crystal-cli vertex list
crystal-cli vertex list --type Person

Get a vertex:

crystal-cli vertex get <id>

Create a vertex:

crystal-cli vertex create Person name=Alice age:=30
crystal-cli vertex create Server ip=10.0.0.1 hostname=web01

The _labels property (with := JSON syntax) sets labels:

crystal-cli vertex create Person name=Alice _labels:='["suspect","witness"]'

Update a vertex:

crystal-cli vertex update <id> age:=31 city=Berlin

Use _type to change the vertex type:

crystal-cli vertex update <id> _type=Organization

Delete a vertex:

crystal-cli vertex delete <id>

This also deletes all connected edges.

List edges of a vertex:

crystal-cli vertex edges <id>
crystal-cli vertex edges <id> --dir out
crystal-cli vertex edges <id> --dir in
crystal-cli vertex edges <id> --dir both

List neighbors:

crystal-cli vertex neighbors <id>
crystal-cli vertex neighbors <id> --dir both

Edges¶

List edges:

crystal-cli edge list
crystal-cli edge list --type knows

Get an edge:

crystal-cli edge get <id>

Create an edge:

crystal-cli edge create <source_id> <target_id> knows since=2020
crystal-cli edge create <source_id> <target_id> accessed port:=443

Special properties: - _weight:=2.5 sets the edge weight - _directed:=false makes the edge undirected

Update an edge:

crystal-cli edge update <id> since=2019
crystal-cli edge update <id> _weight:=3.0

Delete an edge:

crystal-cli edge delete <id>

Queries¶

Query vertices:

crystal-cli query vertices
crystal-cli query vertices --type Person
crystal-cli query vertices --type Person --label suspect
crystal-cli query vertices --type Person --limit 10 --offset 20
crystal-cli query vertices --type Person city=Berlin

Query edges:

crystal-cli query edges
crystal-cli query edges --type knows
crystal-cli query edges --type knows --limit 50

Query neighbors (multi-hop):

crystal-cli query neighbors <vertex_id>
crystal-cli query neighbors <vertex_id> --type Server --depth 2
crystal-cli query neighbors <vertex_id> --dir both --depth 3 --limit 100

Traversal¶

BFS (breadth-first search):

crystal-cli bfs <vertex_id>
crystal-cli bfs <vertex_id> --depth 3
crystal-cli bfs <vertex_id> --depth 5 --dir both --edge-type knows

DFS (depth-first search):

crystal-cli dfs <vertex_id>
crystal-cli dfs <vertex_id> --depth 4 --edge-type accessed

Shortest path:

crystal-cli shortest-path <from_id> <to_id>
crystal-cli shortest-path <from_id> <to_id> --dir both
crystal-cli shortest-path <from_id> <to_id> --edge-type knows

All paths:

crystal-cli all-paths <from_id> <to_id>
crystal-cli all-paths <from_id> <to_id> --depth 4
crystal-cli all-paths <from_id> <to_id> --depth 3 --dir both

Import/Export¶

Export the entire graph to JSON:

crystal-cli export graph.json          # save to file
crystal-cli export                     # print to stdout
crystal-cli export > backup.json       # redirect to file

Import a graph from JSON:

crystal-cli import graph.json

The import creates new vertices and edges with new IDs. Edge source/target references are automatically remapped to the new vertex IDs.

Export format:

{
  "vertices": [
    {
      "id": "...",
      "type": "Person",
      "labels": ["suspect"],
      "properties": {"name": "Alice"},
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "edges": [
    {
      "id": "...",
      "source_id": "...",
      "target_id": "...",
      "type": "knows",
      "properties": {"since": "2020"},
      "directed": true,
      "weight": 1,
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}

Examples¶

Investigation Workflow¶

# Create entities
crystal-cli vertex create Person name="John Doe" email=john@example.com
crystal-cli vertex create Domain fqdn=suspicious.com
crystal-cli vertex create IPAddress ip=203.0.113.42

# Get IDs from output, then link them
crystal-cli edge create $PERSON_ID $DOMAIN_ID registered_domain date=2025-01-15
crystal-cli edge create $DOMAIN_ID $IP_ID resolves_to first_seen=2025-02-01

# Explore connections
crystal-cli vertex neighbors $PERSON_ID --dir out
crystal-cli bfs $PERSON_ID --depth 3

# Find connection between two entities
crystal-cli shortest-path $PERSON_ID $IP_ID --dir both

# Export for reporting
crystal-cli export investigation.json

Dialogue Tree Workflow¶

# Create dialogue nodes
crystal-cli vertex create DialogueNode speaker=NPC text="Welcome, traveler."
crystal-cli vertex create DialogueNode speaker=Player text="Where is the temple?"
crystal-cli vertex create DialogueNode speaker=NPC text="North, past the river."

# Link with choices
crystal-cli edge create $NODE1 $NODE2 choice order:=1
crystal-cli edge create $NODE2 $NODE3 leads_to

# Walk the tree
crystal-cli vertex neighbors $NODE1 --dir out
crystal-cli dfs $NODE1 --depth 10 --edge-type choice