kvs-sh/README.md

# KVS Shell

An interactive command-line client for the KVS (Key-Value Store) distributed database system.

## Overview

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

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

### Install

```bash
# Install to your Go bin directory
go install

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

## Quick Start

1. Start the shell:
```bash
./kvs-shell
```

2. Connect to your KVS server:
```
kvs> connect http://localhost:8090
```

3. Authenticate (if required):
```
kvs> auth eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

4. Store and retrieve data:
```
kvs> put users/alice {"name": "Alice", "email": "alice@example.com"}
kvs> get users/alice
```

## Commands Reference

### Connection & Authentication

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

### Profile Management

```bash
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

```bash
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

```bash
members                                    # List cluster members
health                                     # Check service health
```

### User Management

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

### System Commands

```bash
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:

```bash
# 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:
1. Verify the server is running: `curl http://localhost:8090/health`
2. Check firewall settings
3. Ensure the URL includes the protocol (http:// or https://)

### Authentication Errors

If you get "Unauthorized" errors:
1. Verify your token is still valid (tokens may expire)
2. Check that your user has the required permissions
3. 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

```bash
go build -o kvs-shell
```

### Testing

```bash
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