Godon CLI

A Rust-based CLI tool for controlling and managing the Godon optimizer systemtenders via the Godon Control API.

Features

• Systemtender Management: List, create, show, update, and delete systemtender configurations
• Credential Management: Store and manage SSH keys, API tokens, and other sensitive data
• Target Management: Define and manage target hosts for optimization runs
• Steerwish Management: Declare, list, show, and close steerwishes - declared outcomes (with band, guardrails, and regime) the system holds and tends
• YAML-based Configuration: Simple YAML files for systemtenders, credentials, targets, and steerwishes
• RESTful API Integration: Communicates with the Godon Control API
• Cross-platform Support: Currently Linux x86_64, extensible to other platforms

Installation

Container Image (Recommended)

The godon-cli is distributed as a container image from the godon-images repository. This provides distro-agnostic execution with all dependencies included.

# Run directly
docker run ghcr.io/godon-dev/godon-cli:latest --help

# Example: List systemtenders
docker run ghcr.io/godon-dev/godon-cli:latest systemtender list

# Mount working directory for file operations
docker run -v $(pwd):/work -w /work ghcr.io/godon-dev/godon-cli:latest systemtender create --file config.yaml

Building from Source

You can build the CLI from source using Nix flakes (requires Linux x86_64):

# Clone the repository
git clone https://github.com/godon-dev/godon-cli.git
cd godon-cli

# Build using Nix flakes
nix --experimental-features "nix-command flakes" build

# Run the built binary
./result/bin/godon_cli --help

Usage

Basic Commands

# Show help
godon_cli --help

# List all systemtenders
godon_cli systemtender list

# Connect to a different API server
godon_cli --hostname api.example.com --port 9090 systemtender list

Configuration Options

# Connect to a different API server
godon_cli --hostname api.example.com --port 9090 systemtender list

# Use HTTPS with SSL verification
godon_cli --hostname https://api.example.com --port 443 systemtender list

# Use HTTPS but skip SSL verification (for development/testing)
godon_cli --hostname https://localhost:8443 --insecure systemtender list

Systemtender Management

Create a Systemtender

Create a YAML configuration file systemtender_config.yaml with native YAML syntax:

meta:
  configVersion: "0.2"
  description: "Linux network performance optimization"

systemtender:
  type: "linux_performance"

settings:
  sysctl:
    net.ipv4.tcp_rmem:
      step: 100
      constraints:
        lower: 4096
        upper: 6291456

Then create the systemtender with a name:

godon_cli systemtender create --name "genetic-optimizer-1" --file systemtender_config.yaml

Show Systemtender Details

godon_cli systemtender show --id 550e8400-e29b-41d4-a716-446655440000

Update a Systemtender

Create an update configuration file systemtender_update.yaml with native YAML syntax:

uuid: "550e8400-e29b-41d4-a716-446655440000"
name: "updated-genetic-optimizer"
description: "Updated optimizer configuration"
config:
  setting1: "new_value1"
  setting2: 100
  optimization_target: "throughput"

Then update:

godon_cli systemtender update --file systemtender_update.yaml

Delete a Systemtender

godon_cli systemtender purge --id 550e8400-e29b-41d4-a716-446655440000

Steerwish Management

A steerwish is a declared outcome the system holds and tends: one measured value, a band, guardrails, and (optionally) a rescue budget. Omitted budget means upkeep indefinitely; omitted regime means standing.

Declare a Steerwish

Create a wish file steerwish.yaml:

outcome: "chainend.shift"
band:
  lo: -0.14
  hi: -0.06
  target: -0.10    # receipt and reporting only - the judge needs only the band
limits:
  exclude: []      # param names that may not be moved at all
  maxChange: 0.5   # no input ends further than half its range from neutral
budget: 2          # re-acts after drift; omit for unbounded upkeep
regime: standing   # the only regime today

Then declare it:

godon_cli wish declare --file steerwish.yaml

List Steerwishes

godon_cli wish list

Show a Steerwish (with full event history)

godon_cli wish show --id 550e8400-e29b-41d4-a716-446655440000

Close a Steerwish

godon_cli wish close --id 550e8400-e29b-41d4-a716-446655440000

Credential Management

List Credentials

godon_cli credential list

Create a Credential

Create a YAML configuration file credential.yaml:

name: "production_ssh_key"
credentialType: "ssh_private_key"
description: "SSH key for production servers"
content: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpAIBAAKCAQEA2Z2H7V...
  -----END RSA PRIVATE KEY-----

Then create the credential:

godon_cli credential create --file credential.yaml

Supported credential types:

• ssh_private_key - SSH private keys
• api_token - API authentication tokens
• database_connection - Database connection strings
• http_basic_auth - HTTP basic authentication credentials

Show Credential Details

godon_cli credential show --id 550e8400-e29b-41d4-a716-446655440001

Delete a Credential

godon_cli credential delete --id 550e8400-e29b-41d4-a716-446655440001

Target Management

List Targets

godon_cli target list

Create a Target

Create a YAML configuration file target.yaml:

name: "production-web-01"
targetType: "ssh"
address: "192.168.1.100"
username: "deploy"
description: "Production web server"
allowsDowntime: false

Then create the target:

godon_cli target create --file target.yaml

Show Target Details

godon_cli target show --id 550e8400-e29b-41d4-a716-446655440022

Delete a Target

godon_cli target delete --id 550e8400-e29b-41d4-a716-446655440022

Configuration

The CLI connects to the Godon API using these default settings:

• Hostname: localhost
• Port: 8080
• API Version: v0

You can override these using command-line flags:

# Basic configuration
godon_cli --hostname api.example.com --port 9090 --api-version v1 systemtender list

# Protocol and SSL options
godon_cli --hostname http://api.example.com --port 80 systemtender list     # HTTP (explicit)
godon_cli --hostname https://api.example.com --port 443 systemtender list    # HTTPS (secure)
godon_cli --hostname https://localhost --port 8443 --insecure systemtender list  # HTTPS (insecure)

API Specification

This CLI is designed to work with the Godon Control API which follows OpenAPI 3.0 specification.

License

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details.

Releasing

Releases are source-only through GitHub Actions:

1. Create a new release on GitHub with a semantic version tag (e.g., 1.0.0, 1.0.0-alpha.1)
2. GitHub automatically provides source archives (tar.gz, zip) for the release
3. Container images are built from the godon-images repository using this release

Version format: Must follow Semantic Versioning (e.g., 1.0.0, 2.1.3, 1.0.0-alpha.1, 1.0.0+build.1)

Note: This repository focuses on source code releases. Binary distribution is handled via container images for distro-agnostic compatibility.

Changelog

See the GitHub Releases page for version history and changes.