Interactive Riak Client CLI

A command-line interface for interacting with Riak clusters using the official OpenRiak Riak Java client library.

Features

• TLS Support: Secure connections with robust TLS implementation
• Authentication: Username/password and client certificate authentication
• Full CRUD Operations: Get, Put, Delete operations
• Bucket Management: List buckets and keys
• Interactive Mode: Command-line interface for interactive use
• Certificate Authentication: Full support for mutual TLS with client certificates
• TLS-Only Mode: STARTTLS with optional CA trust and no auth credentials
• HEAD Metadata Output: Prints object metadata and user metadata for head requests

Prerequisites

• Java 21 or higher
• Git (used to clone and build the OpenRiak client from source, default configuration)

Riak Client Configuration

This CLI supports multiple Riak client implementations. You can configure which client to use by editing gradle.properties:

Supported Client Types

1. OpenRiak Client (default) - The OpenRiak Java client, cloned and built from source
2. Custom Client - Use your own JAR file

Configuration

Edit gradle.properties to set the client type:

# Use the OpenRiak client, built from source (default)
riak.client.type=openriak
riak.client.openriak.repository=https://github.com/OpenRiak/riak-java-client.git
riak.client.openriak.ref=main
riak.client.openriak.path=../riak-java-client

# Use custom JAR file
riak.client.type=custom
riak.client.custom.jar.path=/path/to/your/riak-client.jar
riak.client.custom.dependencies=com.example:extra-dep:1.0.0

Quick Client Switching

Use these Gradle tasks to quickly switch between clients:

# Switch to the OpenRiak client (built from source)
./gradlew useOpenRiakClient

# Show current configuration
./gradlew showClientConfig

After switching clients, restart your Gradle daemon:

./gradlew --stop
./gradlew build

Client Type Details

OpenRiak Client (openriak)

• Source: Git repository https://github.com/OpenRiak/riak-java-client.git
• Build: Cloned into riak.client.openriak.path (default ../riak-java-client) and built from source automatically
• Use Case: Default; tracks the OpenRiak client. If the path already contains a checkout, it is reused instead of cloned.

Custom Client (custom)

• Source: Local JAR file path
• Build: Use existing JAR file
• Use Case: Testing custom builds or alternative implementations

Building

The project uses Gradle for building and dependency management:

# Build the project
./gradlew build

# Or use make
make build

The build process will:

1. Download the configured Riak client dependency
2. Compile the Java source code
3. Create a fat JAR with all dependencies included

Creating a Fat JAR

To create a self-contained JAR file that can be run on any machine:

# Create fat JAR
./gradlew shadowJar

# Or use make
make jar

This creates build/libs/riak-cli-fat.jar which includes all dependencies and can be run with:

java -jar build/libs/riak-cli-fat.jar --help

Installation

Build from source and run via the wrapper script:

./gradlew shadowJar
./interactive-riak-cli.sh --help

The wrapper uses build/libs/riak-cli-fat.jar by default.

Usage

Basic Usage

# Connect to local Riak cluster
./interactive-riak-cli.sh

# Connect to remote cluster with TLS
./interactive-riak-cli.sh -h riak.example.com -p port --tls --username user --password pass

# Connect with client certificate authentication
./interactive-riak-cli.sh -h riak.example.com -p port --tls --client-cert /path/to/client-cert.pem --ca-cert /path/to/ca-cert.pem -u username

Command Line Options

Option	Description	Default
-h, --host HOST	Riak host	localhost
-p, --port PORT	Riak port	8087
-u, --username USERNAME	Username for authentication	none
-w, --password PASSWORD	Password for authentication	none
--tls	Use TLS connection	false
--client-cert PATH	Path to client certificate file (PEM with cert and private key)	none
--ca-cert PATH	Path to CA certificate file (PEM)	none
--mcp	Run as MCP stdio server (no interactive prompt)	false
--mcp-stats-port PORT	MCP mode only: HTTP(S) stats port	8098
--mcp-stats-insecure	MCP mode only: disable HTTPS cert/hostname verification for stats	false
--mcp-riak-bin PATH	MCP mode only: explicit riak executable path	PATH lookup
--help	Show help message	-

MCP Mode

Run the CLI as a local MCP server:

./interactive-riak-cli.sh --host riak.example.com --port 10017 --tls --mcp

In --mcp mode:

• The process connects to Riak and serves MCP tools over stdio
• No interactive riak> prompt is started
• Tool surface does not mutate Riak key/value data, but includes operational and security-sensitive read commands
• Always available tools:
  • riak_ping, riak_get, riak_head, riak_list_buckets, riak_list_keys
  • riak_http_stats (calls http(s)://<host>:<mcp-stats-port>/stats)
• Local-only tools (registered only when host is local and riak ping succeeds):
  • riak_cli_ping
  • riak_admin_cluster_status
  • riak_admin_security_status
  • riak_admin_security_print_users
  • riak_admin_security_print_sources
  • riak_admin_ring_status
  • riak_admin_member_status

For client-specific setup, see MCP_SETUP.md and the templates in:

• mcp-config/claude/
• mcp-config/cursor/
• mcp-config/copilot/

Interactive Mode Commands

Once in interactive mode, you can use these commands:

• ping - Test connection to Riak cluster (uses GET request for better permission compatibility)
• get <bucket> <key> - Retrieve a value from Riak
• head <bucket> <key> - Retrieve head only (metadata)
• put <bucket> <key> <value> - Store a value in Riak
• delete <bucket> <key> - Delete a key from Riak
• list-buckets - List all buckets in the cluster (requires list_buckets permission)
• list-keys <bucket> - List all keys in a bucket (requires list_keys permission)
• help - Show available commands
• quit or exit - Exit the CLI

Examples

Basic Operations

# Connect and perform operations
./interactive-riak-cli.sh -p 10017 --tls --username myname --password 123456

riak> put test-bucket test-key "Hello World"
Value stored successfully

riak> get test-bucket test-key
Value: Hello World

riak> delete test-bucket test-key
Key deleted successfully

riak> quit

TLS Connection with Username/Password

# Connect with TLS and username/password authentication
./interactive-riak-cli.sh -h riak.example.com -p 10017 --tls --username user --password pass

TLS Without Authentication

Connect to a Riak cluster using TLS encryption. The CLI enables STARTTLS and does not send auth credentials unless auth credentials are provided.

# TLS-only with custom CA certificate (no username/password)
./interactive-riak-cli.sh -h riak.example.com -p 10017 --tls --ca-cert /path/to/ca.pem

# TLS-only using the JVM default trust store
./interactive-riak-cli.sh -h riak.example.com -p 10017 --tls

HEAD Command Output

head <bucket> <key> prints metadata-oriented output:

• sibling count
• content type
• vclock (when present)
• charset (when present)
• user metadata entries

Certificate Authentication Quick Start

# If you have separate .crt and .key files in RSA format:

# Step 1: Convert RSA private key to PKCS#8
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in client.key -out client.key.pkcs8

# Step 2: Combine certificate and converted key
cat client.crt client.key.pkcs8 > client-combined.pem

# Step 3: Connect with certificate authentication
./interactive-riak-cli.sh -p 10017 --tls \
  --client-cert client-combined.pem \
  --ca-cert ca.crt \
  -u username

Converting Certificate Formats

If you have separate certificate and key files, or RSA format keys, use these commands:

Convert RSA Private Key to PKCS#8

# Convert RSA private key to PKCS#8 format
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private_key.pem -out private_key.pkcs8.pem

Combine Separate Certificate and Key Files

# Combine certificate and PKCS#8 private key into single PEM file
cat certificate.crt private_key.pkcs8.pem > combined.pem

Complete Example: Converting from Separate Files

# Step 1: Convert RSA private key to PKCS#8
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in client.key -out client.key.pkcs8

# Step 2: Combine certificate and converted private key
cat client.crt client.key.pkcs8 > client-combined.pem

# Step 3: Use the combined file for authentication
./interactive-riak-cli.sh -p 10017 --tls \
  --client-cert client-combined.pem \
  --ca-cert ca.crt \
  -u username