client

README

---

🖥️ Plantd Command Line Client

The plantd client is a powerful command-line interface (CLI) tool for interacting with and managing plantd distributed control system services. It provides administrators and developers with direct access to system functionality through an intuitive command structure.

Features

• Service Management: Start, stop, and monitor plantd services
• State Operations: Query and manipulate distributed state across the system
• Echo Testing: Test connectivity and message routing between services
• Configuration: View and modify system configuration settings
• Health Monitoring: Check service health and system status
• Batch Operations: Execute multiple commands via scripts or configuration files

Installation

From Source

# Clone and build
cd client
go build -o plant main.go

# Install globally (optional)
sudo cp plant /usr/local/bin/

Using Make

# Build client from project root
make build-client

# The binary will be available at ./build/plant

Quick Start

Basic Usage

# Show help and available commands
plant --help

# Check version
plant version

# Enable verbose output for debugging
plant --verbose <command>

Configuration

The client uses a configuration file to connect to plantd services:

# Default configuration locations:
# $HOME/.config/plantd/client.yaml
# ./config.yaml

# Example configuration
cat > ~/.config/plantd/client.yaml << EOF
server:
  endpoint: "tcp://localhost:7200"
EOF

Commands

State Management

Interact with the distributed state service:

# Set a key-value pair for a service
plant state set --service="org.plantd.MyService" mykey myvalue

# Get a value by key
plant state get --service="org.plantd.MyService" mykey

# List all keys in a service scope
plant list --service="org.plantd.MyService"

# Delete a key
plant state delete --service="org.plantd.MyService" mykey

# Create a new service scope
plant state create-scope --service="org.plantd.NewService"

# Delete an entire service scope and all its data
plant state delete-scope --service="org.plantd.OldService"

# List all available service scopes
plant state list-scopes

State Command Options

All state commands support the following flags:

• --service: Specify the service scope for operations (default: "org.plantd.Client")
• --profile: Choose authentication profile to use (default: "default")

State Operations Examples

Basic Key-Value Operations:

# Store configuration data
plant state set --service="org.plantd.TempSensor01" config '{"interval": 1000, "unit": "celsius"}'

# Retrieve configuration
plant state get --service="org.plantd.TempSensor01" config

# Update a value
plant state set --service="org.plantd.TempSensor01" current_temp "23.5"

# Delete a specific key
plant state delete --service="org.plantd.TempSensor01" current_temp

Service Discovery and Management:

# See all available services/scopes
plant state list-scopes

# Explore keys in a specific service
plant state list --service="org.plantd.TempSensor01"

# Set up a new service scope
plant state create-scope --service="org.plantd.TempSensor02"

# Remove an entire service and its data
plant state delete-scope --service="org.plantd.OldService"

Working with Different Profiles:

# Use production environment
plant state list-scopes --profile production

# Get data from staging environment  
plant state get --service="org.plantd.MyService" config --profile staging

State Service Authentication

All state operations require authentication. If you haven't logged in, you'll see:

$ plant state list-scopes
Authentication required. Please run 'plant auth login' first.

To authenticate:

# Login to the system
plant auth login

# Then use state commands
plant state list-scopes

Response Format

State operations return JSON responses with a consistent format:

Success Response:

{
  "success": true,
  "data": {
    "scope": "org.plantd.MyService",
    "keys": ["config", "status", "metrics"],
    "count": 3
  }
}

Error Response:

{
  "success": false,
  "error": "Scope 'org.plantd.NonExistent' does not exist"
}

Echo Testing

Test connectivity and message routing:

# Send a simple echo message
plant echo "Hello, plantd!"

# Test with specific service endpoint
plant echo --endpoint="tcp://localhost:5000" "Test message"

# Send multiple echo messages for load testing
plant echo --count=10 "Load test message"

Service Operations

Manage plantd services:

# List all available services
plant services list

# Get detailed service information
plant services info --service="org.plantd.Broker"

# Check service health
plant services health --service="org.plantd.State"

Configuration

Configuration File Format

The client supports YAML configuration files:

# ~/.config/plantd/client.yaml
server:
  endpoint: "tcp://localhost:7200"
  timeout: 30s
  retries: 3

logging:
  level: "info"
  format: "text"

defaults:
  service: "org.plantd.Default"

Environment Variables

Override configuration with environment variables:

# Server endpoint
export PLANTD_CLIENT_ENDPOINT="tcp://production-broker:7200"

# Default service name
export PLANTD_CLIENT_DEFAULT_SERVICE="org.plantd.Production"

# Enable debug logging
export PLANTD_CLIENT_LOG_LEVEL="debug"

Command-Line Flags

Global flags available for all commands:

• --config: Specify custom configuration file path
• --verbose, -v: Enable verbose output
• --endpoint: Override server endpoint
• --timeout: Set request timeout
• --help, -h: Show help information

Examples

Basic State Operations

# Store configuration for a temperature sensor
plant state set --service="org.plantd.TempSensor01" \
  config '{"interval": 1000, "unit": "celsius"}'

# Retrieve the configuration
plant state get --service="org.plantd.TempSensor01" config

# Store current reading
plant state set --service="org.plantd.TempSensor01" \
  current_temp "23.5"

Batch Operations

Create a script for multiple operations:

#!/bin/bash
# setup-sensors.sh

# Create service scopes for multiple sensors
for i in {1..5}; do
  plant state create-scope --service="org.plantd.TempSensor$(printf "%02d" $i)"
  plant state set --service="org.plantd.TempSensor$(printf "%02d" $i)" \
    config '{"interval": 1000, "unit": "celsius"}'
done

Health Monitoring

# Check if all critical services are running
services=("org.plantd.Broker" "org.plantd.State" "org.plantd.Logger")
for service in "${services[@]}"; do
  echo "Checking $service..."
  plant services health --service="$service"
done

Integration

Shell Completion

Generate shell completion scripts:

# Bash
plant completion bash > /etc/bash_completion.d/plant

# Zsh
plant completion zsh > "${fpath[1]}/_plant"

# Fish
plant completion fish > ~/.config/fish/completions/plant.fish

Scripting

The client is designed for automation and scripting:

# Exit codes indicate success/failure
if plant state get --service="org.plantd.Service" key > /dev/null 2>&1; then
  echo "Key exists"
else
  echo "Key not found"
fi

# JSON output for parsing
plant services list --output=json | jq '.services[].name'

Development

Building from Source

# Install dependencies
go mod download

# Build for current platform
go build -o plant main.go

# Cross-compile for different platforms
GOOS=linux GOARCH=amd64 go build -o plant-linux-amd64 main.go
GOOS=windows GOARCH=amd64 go build -o plant-windows-amd64.exe main.go

Adding New Commands

1. Create a new command file in cmd/
2. Implement the command using Cobra
3. Register the command in cmd/cli.go

Example:

// cmd/newcommand.go
package cmd

import (
    "github.com/spf13/cobra"
)

var newCmd = &cobra.Command{
    Use:   "new",
    Short: "Description of new command",
    Run: func(cmd *cobra.Command, args []string) {
        // Implementation
    },
}

func init() {
    // Add flags and configuration
}

Testing

# Run unit tests
go test ./...

# Run integration tests (requires running plantd services)
go test -tags=integration ./...

# Test with different configurations
PLANTD_CLIENT_ENDPOINT="tcp://localhost:7200" go test ./...

Troubleshooting

Common Issues

1. Connection Refused:

   # Check if broker service is running
   plant services health --service="org.plantd.Broker"
   
   # Verify endpoint configuration
   plant --verbose echo "test"
   

2. Permission Denied:

   # Check service permissions
   plant state get --service="org.plantd.Service" --verbose
   

3. Timeout Errors:

   # Increase timeout
   plant --timeout=60s state get --service="org.plantd.Service" key
   

Debug Mode

Enable verbose logging for troubleshooting:

# Global verbose flag
plant --verbose <command>

# Environment variable
export PLANTD_CLIENT_LOG_LEVEL="debug"
plant <command>

Contributing

See the main plantd contributing guide for development setup and guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package main provides the main entry point for the PlantD client.