CLI Reference

ripple-cli is the command-line management tool for Ripple clusters. It provides cluster status, graph inspection, schema listing, checkpoint management, and debug utilities.

Installation

dune build
# Binary at: _build/default/bin/cli/main.exe
# Or via make:
make cli  # runs 'ripple-cli info'

Command Overview

ripple-cli <subcommand>

Subcommands:
  status       Show cluster status
  inspect      Inspect cluster state (graph, schemas, metrics)
  checkpoint   Manage checkpoints
  debug        Debug tools (tap delta streams)
  info         Show version info

info

Display version and build information.

$ ripple-cli info
Ripple v0.1.0-dev
OCaml 5.3.0
Build: incremental graph + heap-based stabilization
Benchmarks: B-01=250ns B-02=82ns B-05=2.1s B-06=129ns

status

Show the overall cluster health.

$ ripple-cli status --coordinator localhost --port 9200
Ripple Cluster Status
----------------------------------------------------
Coordinator:  localhost:9200
Format:       text
Status:       [connected]
Workers:      3/3 active
Partitions:   128 assigned
Epoch:        7

Flags

inspect graph

Inspect the computation graph of a worker. Outputs the graph structure in DOT format (default), sexp, or JSON.

$ ripple-cli inspect graph --worker w0 --format dot
digraph ripple {
  rankdir=TB;
  node [shape=box];
  leaf_0 [label="leaf: AAPL" shape=ellipse];
  leaf_1 [label="leaf: GOOG" shape=ellipse];
  map_0 [label="map: identity"];
  map_1 [label="map: identity"];
  fold_0 [label="fold: sum" shape=diamond];
  leaf_0 -> map_0;
  leaf_1 -> map_1;
  map_0 -> fold_0;
  map_1 -> fold_0;
}

Pipe to Graphviz for visualization:

ripple-cli inspect graph --worker w0 --format dot | dot -Tpng -o graph.png

Flags

inspect schemas

List all registered schemas in the cluster.

$ ripple-cli inspect schemas --verbose
Registered Schemas
----------------------------------------------------
  trade/v1  fp=0a1b2c3d4e5f6789  fields=5
    symbol        : String    (required)
    price         : Float     (required)
    size          : Int       (required)
    timestamp_ns  : Int64     (required)
    venue         : String    (required)

  vwap/v1   fp=9876543210fedcba  fields=4
    symbol        : String    (required)
    vwap          : Float     (required)
    total_volume  : Int       (required)
    trade_count   : Int       (required)

Flags

inspect metrics

Dump the current metrics in Prometheus exposition format.

$ ripple-cli inspect metrics
# TYPE ripple_graph_stabilizations_total counter
ripple_graph_stabilizations_total 0

# TYPE ripple_graph_cutoff_hits_total counter
ripple_graph_cutoff_hits_total 0

# TYPE ripple_graph_node_count gauge
ripple_graph_node_count 0.000000

# TYPE ripple_graph_stabilization_ns histogram
ripple_graph_stabilization_ns_count 0
ripple_graph_stabilization_ns_sum 0.000000
...

This is the same format served by the /metrics endpoint on port 9102. Useful for debugging when Prometheus scraping is not configured.

checkpoint list

List checkpoints for a specific worker.

$ ripple-cli checkpoint list --worker w0 --dir /var/lib/ripple/checkpoints
Checkpoints for worker w0 (dir=/var/lib/ripple/checkpoints)
  Latest: epoch=42 nodes=2000 offsets=1

Flags

debug tap

Tap the live delta stream from a worker’s output. Streams deltas to stdout as they occur, decoded as s-expressions for human readability.

$ ripple-cli debug tap --output vwap --worker w0
Tapping output: vwap
[Connected to w0:9101]

seq=1 key=AAPL delta=(Patch ((Field_set (field_name price) (value 150.25))))
seq=2 key=GOOG delta=(Set ((symbol GOOG)(vwap 2801.5)(total_volume 500)(trade_count 3)))
seq=3 key=AAPL delta=(Patch ((Field_set (field_name price) (value 150.30))))
...
Press Ctrl+C to stop

Flags

Exit Codes

Shell Completion

For bash:

eval "$(ripple-cli complete bash)"

For zsh:

eval "$(ripple-cli complete zsh)"

The CLI is built with Jane Street’s Command module, which provides automatic help text, flag parsing, and subcommand grouping.