KVS Shell is a terminal-based client that provides an intuitive interface for interacting with KVS servers. It offers features similar to mongosh, psql, or redis-cli, allowing you to manage key-value data, users, groups, and cluster members through a simple command interface.

Features

Interactive Shell: Full-featured REPL with command history and auto-completion
Profile Management: Switch between multiple user accounts and servers
Authentication: JWT token-based authentication with secure credential storage
Key-Value Operations: Store, retrieve, and delete JSON data
Cluster Management: Monitor cluster members and health status
User Management: View and manage user accounts (with appropriate permissions)
Colored Output: Syntax-highlighted responses for better readability

Installation

Prerequisites

Go 1.21 or higher
Access to a running KVS server

Build from Source

git clone
cd kvs-shell
go mod tidy
go build -o kvs-shell

Install

# Install to your Go bin directory
go install

# Or copy the binary to your PATH
sudo cp kvs-shell /usr/local/bin/

Quick Start

Start the shell:

./kvs-shell

Connect to your KVS server:

kvs> connect http://localhost:8090

Authenticate (if required):

kvs> auth eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Store and retrieve data:

kvs> put users/alice {"name": "Alice", "email": "alice@example.com"}
kvs> get users/alice

Commands Reference

Connection & Authentication

connect <url>                              # Connect to KVS server
auth <token>                               # Set authentication token

Profile Management

profile                                    # List all saved profiles
profile add <name> <token> <user-uuid> [url]  # Add a new profile
profile use <name>                         # Switch to a profile
profile remove <name>                      # Delete a profile

Example:

kvs> profile add admin eyJhbG... user-uuid-123 http://localhost:8090
kvs> profile add dev eyJhbG... user-uuid-456 http://localhost:8091
kvs> profile use dev

Key-Value Operations

get <key>                                  # Retrieve value for key
put <key> <json>                           # Store JSON value at key
delete <key>                               # Delete key

Examples:

kvs> put config/app {"version": "1.0", "debug": true}
kvs> get config/app
kvs> delete config/old

Cluster Management

members                                    # List cluster members
health                                     # Check service health

User Management

user get <uuid>                            # Get user details
user create <nickname>                     # Create new user (admin only)

System Commands

help                                       # Show help
clear                                      # Clear screen
exit, quit                                 # Exit shell

Response Format

Stored Values

When retrieving data with get, you'll see:

UUID:      a1b2c3d4-e5f6-7890-abcd-ef1234567890
Timestamp: 2025-10-05T12:34:56Z
Data:
{
  "name": "Alice",
  "email": "alice@example.com"
}

Cluster Members

The members command shows:

Cluster Members:
  • node-1 (192.168.1.10:8090) - Last seen: 2025-10-05T12:34:56Z
  • node-2 (192.168.1.11:8090) - Last seen: 2025-10-05T12:35:01Z

Configuration

History

Command history is automatically saved to ~/.kvs_history and persists across sessions.

Profiles

Profiles are stored in memory during the session. To persist profiles across restarts, you can save them to a configuration file (feature to be added in future versions).

Authentication

KVS Shell uses JWT tokens for authentication. Obtain a token from your KVS server administrator or through the server's authentication API:

# Example: Get token from KVS server
curl -X POST http://localhost:8090/api/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"user_uuid": "your-uuid", "scopes": ["read", "write"]}'

Then use the returned token in the shell:

kvs> auth eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Advanced Usage

Working with Complex JSON

For multi-line or complex JSON, use quotes:

kvs> put data/user '{"name": "Bob", "preferences": {"theme": "dark", "notifications": true}}'

Key Naming Conventions

Keys can use path-like structures:

users/alice
config/app/production
data/metrics/2025-10

This helps organize your data hierarchically.

Troubleshooting

Connection Issues

If you can't connect to the server:

Verify the server is running: curl http://localhost:8090/health
Check firewall settings
Ensure the URL includes the protocol (http:// or https://)

Authentication Errors

If you get "Unauthorized" errors:

Verify your token is still valid (tokens may expire)
Check that your user has the required permissions
Generate a new token if needed

Command Not Found

If a command isn't recognized:

Type help to see available commands
Check for typos in the command name
Ensure you've connected to a server first

Development

Building

go build -o kvs-shell

Testing

go test ./...

Dependencies

github.com/chzyer/readline - Interactive line editing and history
github.com/fatih/color - Colored terminal output

Roadmap

Planned features:

Configuration file for persistent profiles
Management of local KVS instance configuration file
Batch operations from file
Export/import functionality
Group management commands
Metadata management
Query filtering and pagination
TLS/SSL support
Shell scripts execution
Tab completion for keys
Transaction support