Godon CLI

A Rust-based CLI tool for managing godon 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 the target hosts systemtenders tend
• Wish Management: Declare, list, show, and close wishes - either an outcome to hold (steer) or a commissioned measured walk (seek)
• YAML-based Configuration: Simple YAML files for systemtenders, credentials, targets, and wishes
• 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

Wish Management

A wish is declared intent, and its file states the type. A steer wish holds one or more measured outcomes in their bands, under optional terms, guardrails, and (optionally) a rescue budget. A seek wish commissions a measured walk over a region of dials.

Declare a Wish

Create a wish file wish.yaml - a steer wish, holding the chain-end shift at -0.10:

type: steer        # the grammar: steer = an outcome to hold
claims:
  - outcome: "chainend.shift"
    band:
      lo: -0.14
      hi: -0.06
      target: -0.10
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 closing rule today

Or a seek wish - find the setting that minimizes the chain-end shift, with a budget of measured trials:

type: seek                     # the grammar: seek = a commissioned walk
form: find_best                # find_best searches; cover_now walks to extend coverage
region:
  chainend.push: [-0.4, 0.4]   # the dials to walk, each [lo, hi]
criterion:
  outcome: "chainend.shift"    # what counts: the reading
  direction: minimize          # ... and the direction
budget: 12                     # measured trials the walk may spend

Then declare it:

godon_cli wish declare --file wish.yaml

List Wishes

godon_cli wish list

Each row states the body's type — and the walk's form when the body is a seek. Both stated, never omitted.

Show a Wish (with full event history)

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

The body prints verbatim, type and form included.

Close a Wish

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

Positions

The standing picture — every live wish's place on the dials, read fresh from the door:

godon_cli positions

Rows come in three kinds and no more: held (a hold's level and bands), measuring (a search's walked window), orphaned (a dead holder's history). The view is derived on every read, never stored.

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.