kestractl

kestractl is a Go-based command-line interface for managing Kestra workflows and related resources. It targets Kestra 2.x (with v1 releases covering the full Kestra 1.x feature set) and is exercised against Kestra 2.0, 1.3, 1.2, 1.1, and 1.0 through an e2e matrix; the source of truth for compatibility is COMPATIBLE_KESTRA_VERSION.properties. Installation is offered through a convenience script (curl | bash) that resolves the latest release via the GitHub REST API, direct binary downloads from GitHub Releases, multi-arch container images published to Docker Hub and GHCR (Alpine and distroless variants), or building from source with Go 1.25+. The install script accepts VERSION and INSTALL_DIR overrides, and can authenticate GitHub API calls with GITHUB_TOKEN to avoid anonymous rate limits. Configuration supports multiple named contexts (dev, staging, prod) stored in ~/.kestractl/config.yaml, with token or basic auth, optional persisted HTTP headers, and a default context selector. Configuration precedence follows the 12-factor model: command-line flags, then KESTRACTL_* environment variables, then the config file, then defaults. Global flags cover --host, --token, --username/--password, --tenant, --header, --output (table or json), --config, and --verbose. Command groups cover the breadth of the Kestra API. Flows: list, list-by-namespace, list-deprecated, get, task, deploy (single file or directory, with --namespace, --override, --fail-fast), validate (local file, directory, or validate-by-query against stored flows), validate-task, validate-trigger, search-by-source, bulk-update, generate-graph-from-source, graph, expressions, namespace-dependencies, dependencies, enable/disable, delete, delete-by-query, disable-by-query, enable-by-query, export (namespace, by-ids, by-query), import, namespace-sync, revisions, delete-revisions, concurrency-limits, update-concurrency. A usage-report command helps verify 1.x to 2.0 migrations, and validate-by-query exits non-zero on violations so it can serve as a CI gate. Executions: run (with --wait), get, list, watch (follows in real time and exits non-zero on failure), latest, kill, pause, resume, restart, force-run, replay, replay-with-inputs, unqueue, set-labels, set-labels-bulk, unqueue-bulk, change-status-by-ids, kill-by-query, pause-by-query, resume-by-query, restart-by-query, replay-by-query, force-run-by-query, delete-by-query, unqueue-by-query, set-labels-by-query, update-status-by-query, trigger-webhook (GET/POST/PUT with optional path suffix), flow-graph, flow-info, flow-info-by-id, download-file, file-metadata, eval-expression, change-status, update-taskrun, delete. Query filters use the FIELD:OPERATION:VALUE form (e.g. STATE:EQUALS:RUNNING). Triggers: list, search-for-flow, enable, disable, unlock, restart, update, delete, plus bulk variants by IDs (namespace/flowId/triggerId) and by query, and backfill management (create-backfill with --start/--end, backfill-pause, backfill-unpause, backfill-delete, and their by-ids and by-query variants). Triggers can also be exported as CSV. Namespaces: list, list with --query, autocomplete, get, create, update, delete, plus setting namespace variables via repeatable --variable or --variables-file, and viewing inherited-secrets and inherited-variables. Key-Value store: list, set, update, get, delete, with supported types STRING, NUMBER, BOOLEAN, DATETIME, DATE, DURATION, JSON, and optional ISO 8601 --ttl. Namespace files: list (with --path and --recursive), get (with --revision), upload (single file or directory, with --override, --fail-fast, --allow-missing-namespace), delete (with --recursive and --force). Plugins: download all plugin JARs for a given Kestra version into a target directory, with --concurrency for parallel downloads, and --from-config to bootstrap a standalone or remote worker by pulling only the core plugins required by a Kestra application.yaml (internal storage, secret manager, queue/repository backend). A list command previews the required core plugins without downloading. Workers: registration-tokens generate runs offline to produce a worker registration token without a Kestra instance. Dashboards (Enterprise Edition): list, get, create from YAML, update, and related management commands. Additional groups cover apps, blueprints, test suites, and IAM (users, groups, roles, service accounts, bindings, invitations). Operational details: kestractl sends anonymous telemetry that never blocks command execution and can be disabled with KESTRACTL_TELEMETRY_DISABLED=true. Update notifications are cached for 24 hours in ~/.kestractl/check_for_new_available_version.json, run asynchronously alongside the command, are skipped on CI and dev builds, and can be disabled with KESTRACTL_VERSION_CHECK_DISABLED=true. The container images run as a non-root user, so config files should be mounted at /home/kestractl/.kestractl (Alpine) or /home/nonroot/.kestractl (static). GitLab CI and GitHub Actions container jobs override the entrypoint and run scripts through a shell, so the default Alpine tag is recommended there; the -static tag has no shell and only works with docker run or kubectl run style invocations.