rapt

README

Rapt

Rapt (from pronunciation of "wrapped") is a CLI utility written in Go that orchestrates running predefined jobs (commands or tools) in a Kubernetes environment.

Overview

Rapt enables you to define, manage, and execute jobs in Kubernetes clusters using a simple command-line interface. It is designed to streamline workflows by providing a consistent and extensible way to run and manage containerized tasks.

Features

• Kubernetes Integration: Native support for Kubernetes clusters
• Custom Resource Definitions: Uses CRDs to define and manage tools
• Simple CLI Interface: Easy-to-use command-line interface
• Extensible: Define custom tools with flexible configuration
• Namespace Support: Work with specific Kubernetes namespaces

Installation

From Source

git clone https://codeberg.org/lig/rapt.git
cd rapt
go build -o rapt main.go
sudo mv rapt /usr/local/bin/

Using Go Install

go install codeberg.org/lig/rapt@latest

Quick Start

1. Initialize Rapt in your cluster:

   rapt init
   

2. Add a tool definition:

   rapt add my-tool --image alpine:latest --command "echo hello world"
   

3. Run a tool:

   rapt run my-tool
   

4. Clean up:

   rapt purge
   

Commands

rapt init

Install the Rapt CRD in your Kubernetes cluster. This command sets up the necessary CustomResourceDefinition so that Rapt can manage and orchestrate predefined jobs in your cluster.

rapt init [--namespace <namespace>]

rapt add

Add a new tool definition to your cluster. Tools are defined using Kubernetes Custom Resources.

rapt add <tool-name> [flags]

Flags:

• --image: Container image to run
• --command: Command to execute (overrides ENTRYPOINT)
• --env: Environment variables (format: KEY=VALUE)
• --help-text: Help message for the tool
• --arg: Tool arguments (format: name:description:required:default)

rapt purge

Remove the Rapt CRD and all associated resources from your Kubernetes cluster.

rapt purge [--namespace <namespace>]

⚠️ Warning: This operation is destructive and cannot be undone.

Tool Definition Schema

Tools are defined using Kubernetes Custom Resources with the following schema:

apiVersion: rapt.dev/v1alpha1
kind: Tool
metadata:
  name: my-tool
spec:
  help: "Description of what this tool does"
  arguments:
    - name: "input"
      description: "Input file path"
      required: true
    - name: "output"
      description: "Output file path"
      required: false
      default: "output.txt"
  jobTemplate:
    image: "alpine:latest"
    command: ["sh", "-c", "echo 'Hello from my-tool'"]
    env:
      - name: "ENV_VAR"
        value: "example-value"

Examples

Simple Echo Tool

rapt add echo-tool \
  --image alpine:latest \
  --command "echo" \
  --arg "message:Message to echo:true:" \
  --help-text "Echo a message"

Database Migration Tool

rapt add db-migrate \
  --image postgres:15 \
  --command "psql" \
  --env "PGHOST=db-service" \
  --env "PGUSER=migrator" \
  --arg "database:Database name:true:" \
  --arg "script:Migration script path:true:" \
  --help-text "Run database migrations"

Development

Prerequisites

• Go 1.24 or later
• Kubernetes cluster (minikube, kind, or cloud provider)
• kubectl configured to access your cluster

Building from Source

git clone https://codeberg.org/lig/rapt.git
cd rapt
go mod download
go build -o rapt main.go

Running Tests

go test ./...

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.

Support

• Issues: Report bugs or request features
• Discussions: Join the community

Roadmap

For detailed development plans and future features, see our ROADMAP.md.

Recent Achievements:

• ✅ Complete MVP functionality with all essential commands
• ✅ Real-time log streaming in rapt run
• ✅ Comprehensive job log management with rapt logs
• ✅ Enhanced job naming with readable timestamps

---

Author: Serge Matveenko lig@countzero.co

Documentation

Overview

Copyright © 2025 Serge Matveenko <lig@countzero.co>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.