nixpkgs/docs/packages/kestractl.md

# kestractl

CLI for the Kestra workflow orchestration platform.

## Description

kestractl is the official command-line interface for [Kestra](https://kestra.io), an open-source workflow orchestration platform. It allows you to interact with Kestra instances to manage flows, trigger executions, inspect namespaces, and automate orchestration tasks from the terminal.

## Features

- 🔄 **Flow Management**: Deploy, inspect, and delete flows
- ▶️ **Execution Control**: Trigger and monitor workflow executions
- 📁 **Namespace Operations**: Manage Kestra namespaces and their resources
- 📂 **Namespace Files**: Upload and manage files in namespace storage
- 🌐 **Multi-Environment**: Switch between dev, staging, and production contexts
- ⚡ **Pre-built Binary**: No compilation required — fetched directly from GitHub releases

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    kestractl
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.kestractl
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#kestractl
```

## Usage

### Basic Commands

```bash
# Check version
kestractl version

# Show help
kestractl --help

# Connect to a Kestra instance
kestractl context set --api-url http://localhost:8080

# List flows in a namespace
kestractl flow list --namespace my.namespace

# Trigger a flow execution
kestractl execution create --namespace my.namespace --flow-id my-flow

# Monitor executions
kestractl execution list --namespace my.namespace
```

## Configuration

kestractl uses a context system to manage connections to Kestra instances:

```bash
# Create a context for a local instance
kestractl context set local --api-url http://localhost:8080

# Create a context for a remote instance with auth
kestractl context set prod --api-url https://kestra.example.com --token <your-token>

# Switch active context
kestractl context use prod
```

## Build Information

- **Version**: 1.0.0
- **Language**: Go (pre-built binary)
- **License**: Apache 2.0
- **Source**: [GitHub](https://github.com/kestra-io/kestractl)

## Platform Support

- `x86_64-linux`
- `aarch64-linux`

## Package Structure

This package uses a `sources.json` + `update.sh` pattern for multi-platform binary fetching:

```
pkgs/kestractl/
├── default.nix    — reads version + hashes from sources.json
├── sources.json   — per-platform URLs and SRI hashes
└── update.sh      — fetches latest GitHub release, updates sources.json
```

Updates are handled by `update.sh` (called by the Gitea Actions nix-update workflow), which fetches the latest release from GitHub, downloads each platform's tarball, computes SRI hashes, and rewrites `sources.json`.

## Related

- [Kestra Documentation](https://kestra.io/docs)
- [kestractl GitHub](https://github.com/kestra-io/kestractl)
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide