{"id":45691553,"url":"https://github.com/kestra-io/kestractl","last_synced_at":"2026-06-30T11:32:14.626Z","repository":{"id":317499387,"uuid":"1067676269","full_name":"kestra-io/kestractl","owner":"kestra-io","description":"A Go-based command-line interface for managing Kestra flows, executions, and namespaces.","archived":false,"fork":false,"pushed_at":"2026-06-18T13:21:39.000Z","size":7055,"stargazers_count":5,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T15:11:42.043Z","etag":null,"topics":["cli","cobra","golang","viper"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kestra-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T08:07:30.000Z","updated_at":"2026-06-17T08:31:56.000Z","dependencies_parsed_at":"2025-10-01T10:14:20.305Z","dependency_job_id":"3b24f5fb-fc51-4422-bc2d-c32ad31b1563","html_url":"https://github.com/kestra-io/kestractl","commit_stats":null,"previous_names":["kestra-io/kestra-cli","kestra-io/kestractl"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/kestra-io/kestractl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestra-io%2Fkestractl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestra-io%2Fkestractl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestra-io%2Fkestractl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestra-io%2Fkestractl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kestra-io","download_url":"https://codeload.github.com/kestra-io/kestractl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestra-io%2Fkestractl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34965642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cobra","golang","viper"],"created_at":"2026-02-24T18:03:26.948Z","updated_at":"2026-06-30T11:32:14.607Z","avatar_url":"https://github.com/kestra-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kestra CLI\n\nA Go-based command-line interface for managing Kestra flows, executions, triggers, namespaces, key-value store, namespace files, apps, dashboards, assets, blueprints, test suites, IAM users, groups, roles, service accounts, bindings, and invitations.\n\n## Installation\n\n### use convenience script installer\nInstall the latest release (macOS/Linux):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/kestra-io/kestractl/main/install-scripts/install.sh | bash\n```\n\nInstall a specific version or custom directory:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/kestra-io/kestractl/main/install-scripts/install.sh | VERSION=1.0.0 INSTALL_DIR=~/.local/bin bash\n```\n\n### or choose and download the proper binary for your OS/arch\ndownload the compressed or plain binary for your platform at https://github.com/kestra-io/kestractl/releases\n\nexample:\n```\ncurl -fsSL -o kestractl https://github.com/kestra-io/kestractl/releases/download/1.0.0/kestractl_1.0.0_linux_arm64\nchmod +x kestractl\n```\n\n### or compile it\n```bash\ngit clone git@github.com:kestra-io/kestractl.git\n\n# Download dependencies (requires Go 1.25+)\ngo mod download\n\n# Build the binary\ngo build -o kestractl\n```\n\nYou can also install it into your `$GOBIN`:\n\n```bash\ngo install ./...\n```\n\n## Quick Setup\n\nConfigure your Kestra instance and credentials:\n\n```bash\n# Token auth\nkestractl config add default http://localhost:8080 main --token YOUR_TOKEN --default\n\n# Basic auth (username + password)\nkestractl config add default http://localhost:8080 main --username you@example.com --password YOUR_PASSWORD --default\n```\n\nThis creates a configuration file at `~/.kestractl/config.yaml`:\n\n```yaml\ncontexts:\n  default:\n    host: http://localhost:8080\n    tenant: main\n    auth_method: token\n    token: YOUR_TOKEN\n    headers:                     # Optional: persisted extra HTTP headers\n      - \"X-Custom-Header:value\"\ndefault_context: default\n```\n\n### Multiple Contexts\n\nYou can manage multiple Kestra environments (development, staging, production):\n\n```bash\n# Add multiple contexts\nkestractl config add dev http://localhost:8080 main --token DEV_TOKEN\nkestractl config add prod https://prod.kestra.io production --token PROD_TOKEN\n\n# List all contexts\nkestractl config show\n\n# Switch between contexts\nkestractl config use prod\n```\n\n### Environment Variables\n\nYou can also configure the CLI using environment variables, which override config file settings:\n\n```bash\nexport KESTRACTL_HOST=http://localhost:8080\nexport KESTRACTL_TENANT=main\nexport KESTRACTL_TOKEN=YOUR_TOKEN\nexport KESTRACTL_OUTPUT=json                       # Optional: table or json\nexport KESTRACTL_HEADER=\"X-Custom-Header:value\"   # Optional: extra HTTP header\n```\n\n### Configuration Precedence\n\nFollowing the [12-factor app](https://12factor.net/config) methodology, configuration is resolved in this order (highest to lowest):\n\n1. **Command-line flags** (`--host`, `--token`, etc.) - Highest priority\n2. **Environment variables** (`KESTRACTL_HOST`, `KESTRACTL_TOKEN`, etc.)\n3. **Config file** (`~/.kestractl/config.yaml` or custom via `--config`)\n4. **Default values** - Lowest priority\n\nThis allows you to:\n- Store credentials securely in `~/.kestractl/config.yaml` for daily use\n- Override with environment variables in CI/CD pipelines\n- Override with flags for one-off commands\n\n### Telemetry\n\nThe CLI sends anonymous telemetry to help the Kestra team understand real usage and improve the product over time, and it never blocks command execution.\n\nSet `KESTRACTL_TELEMETRY_DISABLED=true` to disable telemetry.\n\n## Usage\n\nAll commands support global flags for connection and output configuration:\n- `--host` - Kestra host URL\n- `--token` / `-t` - API authentication token\n- `--username` - Basic auth username (alternative to `--token`)\n- `--password` - Basic auth password (alternative to `--token`)\n- `--tenant` - Tenant name\n- `--header` - Extra HTTP header to include in all requests (format: `Key:Value`, repeatable)\n- `--output` / `-o` - Output format (`table` or `json`)\n- `--config` - Custom config file path (default: `~/.kestractl/config.yaml`)\n- `--verbose` / `-v` - Verbose output (warning: prints credentials in HTTP requests)\n\n### Config Management\n\n```bash\n# Add a new context\nkestractl config add dev http://localhost:8080 main --token YOUR_TOKEN\n\n# Add and set as default\nkestractl config add prod https://prod.kestra.io production --token PROD_TOKEN --default\n\n# Add with extra HTTP headers (persisted in the context)\nkestractl config add dev http://localhost:8080 main --token YOUR_TOKEN \\\n  --header \"X-Custom-Header:value\" --header \"Authorization:Bearer extra\"\n\n# List all contexts\nkestractl config show\n\n# Switch default context\nkestractl config use prod\n\n# Remove a context\nkestractl config remove dev\n```\n\n### Flows\n\n```bash\n# List flows in a namespace (alias: ls)\nkestractl flows list my.namespace\n\n# List flows across all namespaces\nkestractl flows list\n\n# List flows in a namespace with pagination\nkestractl flows list-by-namespace my.namespace --page 1 --size 50\n\n# List deprecated flows\nkestractl flows list-deprecated\n\n# Get a flow source (aliases: show, describe)\nkestractl flows get my.namespace my-flow\n\n# Get a specific task within a flow\nkestractl flows task my.namespace my-flow my-task-id\n\n# Deploy a single flow from YAML (aliases: create, apply)\nkestractl flows deploy path/to/flow.yaml\n\n# Deploy all flows in a directory (recursive)\nkestractl flows deploy ./flows/\n\n# Deploy with namespace override (all flows go to specified namespace)\nkestractl flows deploy ./flows/ --namespace prod.namespace\n\n# Override existing flows\nkestractl flows deploy ./flows/ --override\n\n# Stop on first error (fail-fast)\nkestractl flows deploy ./flows/ --fail-fast\n\n# Validate a single flow or directory\nkestractl flows validate path/to/flow.yaml\nkestractl flows validate ./flows/\n\n# Validate a task or trigger definition inline\nkestractl flows validate-task --namespace my.namespace --flow my-flow --task-id my-task\nkestractl flows validate-trigger --namespace my.namespace --flow my-flow --trigger-id my-trigger\n\n# Search flows by source content\nkestractl flows search-by-source --query \"http.request\"\n\n# Bulk-update flows from YAML\nkestractl flows bulk-update --file flows.yaml\n\n# Generate the graph topology from a flow source file\nkestractl flows generate-graph-from-source --file flow.yaml\n\n# Show the graph topology of an existing flow (optionally a specific revision)\nkestractl flows graph my.namespace my-flow --revision 3 --output json\n\n# List available expressions for a flow\nkestractl flows expressions --namespace my.namespace --flow my-flow\n\n# Show namespace-level dependencies\nkestractl flows namespace-dependencies my.namespace\n\n# Show dependencies of a specific flow\nkestractl flows dependencies my.namespace my-flow\n\n# Enable / disable flows\nkestractl flows enable my.namespace my-flow\nkestractl flows disable my.namespace my-flow\n\n# Delete a flow\nkestractl flows delete my.namespace my-flow\n\n# Delete / disable / enable matching a query\nkestractl flows delete-by-query --namespace my.namespace --query old-\nkestractl flows disable-by-query --namespace my.namespace\nkestractl flows enable-by-query --namespace my.namespace\n\n# Export flows\nkestractl flows export --namespace my.namespace --output-file flows.zip\nkestractl flows export-by-ids my.namespace/flow-a my.namespace/flow-b --output-file export.zip\nkestractl flows export-by-query --namespace my.namespace --output-file export.zip\n\n# Import flows from a ZIP archive\nkestractl flows import flows.zip\n\n# Sync an entire namespace from a YAML file (delete flows absent from the file)\nkestractl flows namespace-sync my.namespace flows.yaml --delete --override\n\n# View and manage flow revisions\nkestractl flows revisions my.namespace my-flow\nkestractl flows delete-revisions my.namespace my-flow --before-revision 5\n\n# Manage concurrency limits\nkestractl flows concurrency-limits my.namespace my-flow\nkestractl flows update-concurrency my.namespace my-flow --limit 10\n```\n\n### Executions\n\n```bash\n# Trigger a flow execution (aliases: trigger, execute)\nkestractl executions run my.namespace my-flow\n\n# Trigger and wait for completion\nkestractl executions run my.namespace my-flow --wait\n\n# Get execution details (aliases: show, describe)\nkestractl executions get 2TLGqHrXC9k8BczKJe5djX\n\n# List executions\nkestractl executions list --namespace my.namespace --flow my-flow\n\n# Watch an execution in real time (alias: follow) — exits non-zero on failure\nkestractl executions watch 2TLGqHrXC9k8BczKJe5djX\n\n# Get the latest execution for each flow\nkestractl executions latest --flow my.namespace:my-flow --flow my.namespace:other-flow\n\n# Control execution state\nkestractl executions kill   2TLGqHrXC9k8BczKJe5djX\nkestractl executions pause  2TLGqHrXC9k8BczKJe5djX\nkestractl executions resume 2TLGqHrXC9k8BczKJe5djX\nkestractl executions restart 2TLGqHrXC9k8BczKJe5djX\nkestractl executions force-run 2TLGqHrXC9k8BczKJe5djX\n\n# Replay and unqueue\nkestractl executions replay 2TLGqHrXC9k8BczKJe5djX\nkestractl executions replay-with-inputs 2TLGqHrXC9k8BczKJe5djX --input key=value\nkestractl executions unqueue 2TLGqHrXC9k8BczKJe5djX\n\n# Labels\nkestractl executions set-labels 2TLGqHrXC9k8BczKJe5djX env=prod team=platform\n\n# Bulk operations by IDs\nkestractl executions set-labels-bulk env=prod --ids id1 --ids id2\nkestractl executions unqueue-bulk id1 id2 id3\nkestractl executions change-status-by-ids --status SUCCESS id1 id2\n\n# Bulk operations by query\nkestractl executions kill-by-query    --namespace my.namespace --flow my-flow\nkestractl executions pause-by-query   --namespace my.namespace\nkestractl executions resume-by-query  --namespace my.namespace\nkestractl executions restart-by-query --namespace my.namespace\nkestractl executions replay-by-query  --namespace my.namespace --latest-revision\nkestractl executions force-run-by-query --namespace my.namespace\nkestractl executions delete-by-query  --namespace my.namespace --delete-logs --delete-storage\nkestractl executions unqueue-by-query --namespace my.namespace\nkestractl executions set-labels-by-query env=prod --namespace my.namespace\nkestractl executions update-status-by-query --namespace my.namespace --new-status KILLED\n# Filter by any field with --filter FIELD:OPERATION:VALUE (e.g. STATE:EQUALS:SUCCESS)\nkestractl executions kill-by-query --filter STATE:EQUALS:RUNNING\n\n# Trigger an execution via webhook (--method GET|POST|PUT, --path appends a URL suffix)\nkestractl executions trigger-webhook my.namespace my-flow my-webhook-key\nkestractl executions trigger-webhook my.namespace my-flow my-webhook-key --method POST\nkestractl executions trigger-webhook my.namespace my-flow my-webhook-key --method PUT --path extra/segment\n\n# Flow graph and info\nkestractl executions flow-graph 2TLGqHrXC9k8BczKJe5djX\nkestractl executions flow-info my.namespace my-flow\nkestractl executions flow-info-by-id 2TLGqHrXC9k8BczKJe5djX\n\n# Download execution output files\nkestractl executions download-file 2TLGqHrXC9k8BczKJe5djX --path outputs/result.csv\nkestractl executions file-metadata 2TLGqHrXC9k8BczKJe5djX --path outputs/result.csv\n\n# Evaluate an expression against an execution\nkestractl executions eval-expression 2TLGqHrXC9k8BczKJe5djX \"{{ outputs.myTask.value }}\"\n\n# Force-change the status of an execution\nkestractl executions change-status 2TLGqHrXC9k8BczKJe5djX SUCCESS\n\n# Update a specific task run's state\nkestractl executions update-taskrun 2TLGqHrXC9k8BczKJe5djX taskRunId SUCCESS\n\n# Delete an execution\nkestractl executions delete 2TLGqHrXC9k8BczKJe5djX\n```\n\n### Triggers\n\n```bash\n# List all triggers\nkestractl triggers list\n\n# List triggers for a specific flow\nkestractl triggers search-for-flow my.namespace my-flow\n\n# Enable / disable a trigger\nkestractl triggers enable  my.namespace my-flow my-trigger\nkestractl triggers disable my.namespace my-flow my-trigger\n\n# Unlock a locked trigger\nkestractl triggers unlock my.namespace my-flow my-trigger\n\n# Restart a trigger\nkestractl triggers restart my.namespace my-flow my-trigger\n\n# Update a trigger (e.g. mark disabled)\nkestractl triggers update my.namespace my-flow my-trigger --disabled\n\n# Delete a trigger\nkestractl triggers delete my.namespace my-flow my-trigger\n\n# Bulk operations by IDs (format: namespace/flowId/triggerId)\nkestractl triggers delete-by-ids  my.ns/my-flow/sched my.ns/my-flow/webhook\nkestractl triggers unlock-by-ids  my.ns/my-flow/sched\nkestractl triggers disable-by-ids my.ns/my-flow/sched\nkestractl triggers enable-by-ids  my.ns/my-flow/sched\n\n# Bulk operations by query\nkestractl triggers delete-by-query  --namespace my.namespace\nkestractl triggers unlock-by-query  --namespace my.namespace\nkestractl triggers disable-by-query --namespace my.namespace\nkestractl triggers enable-by-query  --namespace my.namespace\n\n# Backfill management (single trigger)\nkestractl triggers create-backfill my.namespace my-flow my-trigger \\\n  --start 2024-01-01T00:00:00Z --end 2024-02-01T00:00:00Z\nkestractl triggers backfill-pause   my.namespace my-flow my-trigger\nkestractl triggers backfill-unpause my.namespace my-flow my-trigger\nkestractl triggers backfill-delete  my.namespace my-flow my-trigger\n\n# Backfill management by IDs\nkestractl triggers pause-backfill-by-ids   my.ns/my-flow/sched\nkestractl triggers unpause-backfill-by-ids my.ns/my-flow/sched\nkestractl triggers delete-backfill-by-ids  my.ns/my-flow/sched\n\n# Backfill management by query\nkestractl triggers pause-backfill-by-query   --namespace my.namespace\nkestractl triggers unpause-backfill-by-query --namespace my.namespace\nkestractl triggers delete-backfill-by-query  --namespace my.namespace\n\n# Export all triggers as CSV\nkestractl triggers export-csv\nkestractl triggers export-csv --output-file triggers.csv\n```\n\n### Namespaces\n\n```bash\n# List all namespaces (alias: ls)\nkestractl namespaces list\n\n# Filter namespaces with query\nkestractl namespaces list --query my.namespace\n\n# Autocomplete namespace names\nkestractl namespaces autocomplete --query my.\n\n# Get namespace details\nkestractl namespaces get my.namespace\n\n# Create / update / delete a namespace\nkestractl namespaces create my.namespace\nkestractl namespaces update my.namespace --description \"Production namespace\"\nkestractl namespaces delete my.namespace\n\n# View inherited secrets and variables\nkestractl namespaces inherited-secrets   my.namespace\nkestractl namespaces inherited-variables my.namespace\n\n# Plugin defaults for a namespace (inherited configuration)\nkestractl namespaces plugin-defaults my.namespace\n\n# Export / import plugin defaults\nkestractl namespaces export-plugin-defaults my.namespace --output-file defaults.yaml\nkestractl namespaces import-plugin-defaults my.namespace defaults.yaml\n```\n\n### Key-Value Store (kv)\n\nSupported types: `STRING`, `NUMBER`, `BOOLEAN`, `DATETIME`, `DATE`, `DURATION`, `JSON`\n\n```bash\n# List all key-value entries\nkestractl kv list\n\n# List key-value entries in a namespace\nkestractl kv list my.namespace\n\n# Set a key — format: kv set \u003cnamespace\u003e \u003ctype\u003e \u003ckey\u003e \u003cvalue\u003e\nkestractl kv set my.namespace STRING api_key \"my-secret\"\nkestractl kv set my.namespace NUMBER retries 3\nkestractl kv set my.namespace BOOLEAN enabled true\nkestractl kv set my.namespace JSON settings '{\"feature\":true}'\n\n# Set a key with a TTL (ISO 8601 duration)\nkestractl kv set my.namespace STRING session_token \"abc\" --ttl PT1H\nkestractl kv set my.namespace STRING cache_key \"value\" --ttl P7D\n\n# Update an existing key (fails if key does not exist)\nkestractl kv update my.namespace NUMBER retries 5\nkestractl kv update my.namespace STRING session_token \"new\" --ttl PT30M\n\n# Read a key (shows type and value)\nkestractl kv get my.namespace api_key\n\n# Delete a key (alias: rm)\nkestractl kv delete my.namespace api_key\n```\n\n### Namespace Files (nsfiles)\n\n```bash\n# List files at the namespace root (alias: ls)\nkestractl nsfiles list my.namespace\n\n# List files in a directory\nkestractl nsfiles list my.namespace --path workflows/\n\n# List files recursively\nkestractl nsfiles list my.namespace --path workflows/ --recursive\n\n# Get a file's raw content (alias: cat)\nkestractl nsfiles get my.namespace workflows/example.yaml\n\n# Get a specific revision\nkestractl nsfiles get my.namespace workflows/example.yaml --revision 3\n\n# Upload a single file\nkestractl nsfiles upload my.namespace ./local.txt workflows/local.txt\n\n# Upload a directory (recursive)\nkestractl nsfiles upload my.namespace ./assets resources\n\n# Override existing files\nkestractl nsfiles upload my.namespace ./assets resources --override\n\n# Stop on the first error\nkestractl nsfiles upload my.namespace ./assets resources --fail-fast\n\n# Skip the pre-flight namespace existence check\nkestractl nsfiles upload my.namespace ./assets resources --allow-missing-namespace\n\n# Delete a file\nkestractl nsfiles delete my.namespace workflows/example.yaml\n\n# Delete a directory recursively\nkestractl nsfiles delete my.namespace workflows --recursive\n\n# Ignore missing targets\nkestractl nsfiles delete my.namespace workflows/example.yaml --force\n```\n\n### Plugins\n\n```bash\n# Download every plugin JAR for a given Kestra version into ./plugins\nkestractl plugins download 1.3.9\n\n# Custom output directory\nkestractl plugins download 1.3.9 --plugins-dir ./vendor/plugins\n\n# Parallel downloads\nkestractl plugins download 1.3.9 --concurrency 4\n\n# `develop` and `latest` are aliases for the in-development version\nkestractl plugins download develop\n\n# Bootstrap a standalone/remote worker: download only the \"core\" plugins required\n# by a Kestra configuration — internal storage, secret manager, and the\n# queue/repository backend. Bundled backends (local storage, JDBC, Kafka) are\n# skipped; enterprise backends need --edition ALL (the default) or EE.\nkestractl plugins download 1.3.9 --from-config /etc/kestra/application.yaml\n\n# Preview the core plugins a config needs without downloading (pipes into download)\nkestractl plugins list 1.3.9 --from-config /etc/kestra/application.yaml\n```\n\n### Workers\n\n```bash\n# Generate a worker registration token (runs offline, no Kestra instance required)\nkestractl workers registration-tokens generate\n```\n\n### Dashboards (Enterprise Edition)\n\n```bash\n# List dashboards (alias: ls)\nkestractl dashboards list\nkestractl dashboards list --query my-dashboard --output json\n\n# Get dashboard details (aliases: show, describe)\nkestractl dashboards get \u003cid\u003e\n\n# Create a dashboard from a YAML file\nkestractl dashboards create --file my-dashboard.yaml\n\n# Update an existing dashboard\nkestractl dashboards update \u003cid\u003e --file my-dashboard.yaml\n\n# Delete a dashboard (alias: rm)\nkestractl dashboards delete \u003cid\u003e\n\n# Show the tenant's default dashboard settings\nkestractl dashboards defaults\n\n# Validate a dashboard or a single chart definition\nkestractl dashboards validate --file my-dashboard.yaml\nkestractl dashboards validate-chart --file my-chart.yaml\n\n# Preview a chart's data without saving it\nkestractl dashboards preview-chart --file my-chart.yaml --output json\n\n# Fetch the data for a chart of an existing dashboard\nkestractl dashboards chart-data \u003cdashboard-id\u003e \u003cchart-id\u003e\nkestractl dashboards chart-data \u003cdashboard-id\u003e \u003cchart-id\u003e --file filters.yaml --output json\n\n# Export chart data as CSV (to stdout or --output-file)\nkestractl dashboards export-chart-csv --file my-chart.yaml --output-file chart.csv\nkestractl dashboards export-chart-data-csv \u003cdashboard-id\u003e \u003cchart-id\u003e --output-file chart.csv\n```\n\n### Apps (Enterprise Edition)\n\nApps are low-code interfaces built on top of flows.\n\n```bash\n# List apps (alias: ls)\nkestractl apps list\nkestractl apps list --namespace my.namespace --output json\n\n# Get app details (aliases: show, describe)\nkestractl apps get \u003cuid\u003e\n\n# Deploy a new app from a YAML file\nkestractl apps deploy --file my-app.yaml\n\n# Update an existing app\nkestractl apps update \u003cuid\u003e --file my-app.yaml\n\n# Enable / disable an app\nkestractl apps enable  \u003cuid\u003e\nkestractl apps disable \u003cuid\u003e\n\n# Delete an app (alias: rm)\nkestractl apps delete \u003cuid\u003e\n\n# Export all apps as a ZIP archive\nkestractl apps export --output-file apps.zip\n\n# Import apps from a ZIP archive\nkestractl apps import apps.zip\n\n# Bulk enable / disable / delete multiple apps\nkestractl apps bulk-enable  uid-1 uid-2 uid-3\nkestractl apps bulk-disable uid-1 uid-2 uid-3\nkestractl apps bulk-delete  uid-1 uid-2 --yes\n\n# List all tags used across apps\nkestractl apps tags\n\n# Search apps from the catalog\nkestractl apps catalog\nkestractl apps catalog --query reporting --output json\n\n# Inspect files produced by an app execution view\nkestractl apps file-meta    \u003cview-id\u003e --path /path/to/file\nkestractl apps file-preview \u003cview-id\u003e --path /path/to/file --max-rows 50\n\n# Download logs for an app execution\nkestractl apps logs \u003cview-id\u003e --min-level ERROR --output-file app.log\n```\n\n### Assets (Enterprise Edition)\n\n```bash\n# List assets (alias: ls)\nkestractl assets list\nkestractl assets list --output json\n\n# Get asset details (aliases: show, describe)\nkestractl assets get \u003cid\u003e\n\n# Create an asset from a file\nkestractl assets create --name my-asset --file asset.csv\n\n# Delete an asset (alias: rm)\nkestractl assets delete \u003cid\u003e\n\n# Show an asset's dependency graph (alias: deps)\nkestractl assets dependencies \u003cid\u003e --expand-all --output json\n\n# Bulk-delete assets by IDs or by query filters\nkestractl assets delete-by-ids id1 id2 id3\nkestractl assets delete-by-query --namespace my.namespace\nkestractl assets delete-by-query --filter NAMESPACE:EQUALS:my.namespace --purge\n\n# Inspect and manage lineage events (alias: lineage)\nkestractl assets lineage-events list --output json\nkestractl assets lineage-events delete-by-query --namespace my.namespace\n\n# Inspect and manage asset usages (alias: usage)\nkestractl assets usages list --output json\nkestractl assets usages delete-by-query --namespace my.namespace\n```\n\n### Blueprints\n\n```bash\n# Search community blueprints\nkestractl blueprints community search --query \"kafka\"\nkestractl blueprints community search --query \"etl\" --output json\n\n# Get a community blueprint\nkestractl blueprints community get \u003cid\u003e\n\n# Get the flow source of a community blueprint\nkestractl blueprints community source \u003cid\u003e\n\n# Get the topology graph of a community blueprint\nkestractl blueprints community graph \u003cid\u003e --output json\n\n# Manage internal flow blueprints (Enterprise Edition)\nkestractl blueprints flow list\nkestractl blueprints flow get \u003cid\u003e\nkestractl blueprints flow get \u003cid\u003e --legacy   # use the legacy /blueprints/flow/{id} endpoint\nkestractl blueprints flow create --title \"My Blueprint\" --source-file blueprint.yaml --tag etl\nkestractl blueprints flow update \u003cid\u003e --title \"My Blueprint\" --source-file blueprint.yaml\nkestractl blueprints flow delete \u003cid\u003e\n\n# Generate a flow source from a flow blueprint template\nkestractl blueprints flow use-template \u003cid\u003e --input env=prod --input region=eu\n\n# Manage internal/custom blueprints (Enterprise Edition)\nkestractl blueprints custom get \u003cid\u003e\nkestractl blueprints custom source \u003cid\u003e\nkestractl blueprints custom create --title \"My Blueprint\" --source-file blueprint.yaml\nkestractl blueprints custom update \u003cid\u003e --title \"My Blueprint\" --source-file blueprint.yaml\nkestractl blueprints custom delete \u003cid\u003e\n```\n\n### Test Suites (Enterprise Edition)\n\n```bash\n# List test suites (alias: ls)\nkestractl test-suites list\nkestractl test-suites list --namespace my.namespace\n\n# Get a test suite\nkestractl test-suites get my.namespace my-test-suite\n\n# Create / update a test suite from a YAML file\nkestractl test-suites create --file suite.yaml\nkestractl test-suites update my.namespace my-test-suite --file suite.yaml\n\n# Validate a test suite YAML definition without creating it\nkestractl test-suites validate --file suite.yaml\n\n# Run a test suite\nkestractl test-suites run my.namespace my-test-suite\n\n# Run test suites matching a query\nkestractl test-suites run-by-query --namespace my.namespace\n\n# Bulk enable / disable / delete\nkestractl test-suites delete-bulk my.namespace/suite-a my.namespace/suite-b\nkestractl test-suites disable-bulk my.namespace/suite-a\nkestractl test-suites enable-bulk  my.namespace/suite-a\n\n# Query and retrieve results\nkestractl test-suites search-results --namespace my.namespace\nkestractl test-suites last-result --ids my.namespace/suite-a --ids my.namespace/suite-b\nkestractl test-suites get-result \u003cresult_id\u003e\n\n# Delete a test suite\nkestractl test-suites delete my.namespace my-test-suite\n```\n\n### Users (Enterprise Edition)\n\nUser management requires Kestra Enterprise Edition. Users are instance-level resources.\n\n\u003e Use `--user-password` to set a user's password — not `--password`, which is the\n\u003e global basic-auth flag used to authenticate the CLI itself.\n\n```bash\n# List / filter users (alias: ls)\nkestractl users list\nkestractl users list --query alice --output json\n\n# Get user details (alias: show, describe)\nkestractl users get \u003cuser_id\u003e\n\n# Autocomplete user names\nkestractl users autocomplete --query ali\n\n# Create a user (--email is required)\nkestractl users create --email alice@example.com --first-name Alice --user-password 'S3cret!'\n\n# Create a super-admin\nkestractl users create --email bob@example.com --superadmin\n\n# Update a user — only the flags you pass change; other attributes are preserved\nkestractl users update \u003cuser_id\u003e --first-name Alicia\nkestractl users update \u003cuser_id\u003e --superadmin=false\n\n# Set a user's password\nkestractl users set-password \u003cuser_id\u003e --user-password 'N3wPass!'\n\n# Change your own password\nkestractl users change-my-password --old-password 'OldPass!' --new-password 'N3wPass!'\n\n# Grant / revoke super-admin status\nkestractl users set-super-admin \u003cuser_id\u003e --superadmin\nkestractl users set-super-admin \u003cuser_id\u003e --superadmin=false\n\n# Mark a user as restricted, or lift the restriction (targeted PATCH)\nkestractl users set-restricted \u003cuser_id\u003e --restricted=true\nkestractl users set-restricted \u003cuser_id\u003e --restricted=false\n\n# Delete an auth method for a user\nkestractl users delete-auth-method \u003cuser_id\u003e BASIC_AUTH\n\n# Set the groups a user belongs to in the active tenant (no --group clears them)\nkestractl users set-groups \u003cuser_id\u003e --group \u003cgroup_id\u003e\n\n# Impersonate a user (returns an impersonation token)\nkestractl users impersonate \u003cuser_id\u003e\n\n# Revoke all refresh tokens for a user\nkestractl users revoke-refresh-token \u003cuser_id\u003e\n\n# Delete a user (alias: rm) — prompts for confirmation unless --yes\nkestractl users delete \u003cuser_id\u003e\nkestractl users delete \u003cuser_id\u003e --yes\n\n# Manage a user's API tokens (the full token is shown only once, at creation)\nkestractl users tokens create \u003cuser_id\u003e --name ci-token\nkestractl users tokens list \u003cuser_id\u003e\nkestractl users tokens delete \u003cuser_id\u003e \u003ctoken_id\u003e\n```\n\n### Groups (Enterprise Edition)\n\nGroup management requires Kestra Enterprise Edition. Groups are tenant-scoped resources.\n\n```bash\n# List / filter groups (alias: ls)\nkestractl groups list\nkestractl groups list --query admins --output json\n\n# Get group details (alias: show, describe)\nkestractl groups get \u003cgroup_id\u003e\n\n# Autocomplete group names\nkestractl groups autocomplete --query adm\n\n# Look up multiple groups by IDs\nkestractl groups list-by-ids \u003cid1\u003e \u003cid2\u003e\n\n# Create a group (--name is required; --member is repeatable for initial members)\nkestractl groups create --name admins --description 'Platform admins'\nkestractl groups create --name admins --member \u003cuser_id\u003e --member \u003cuser_id\u003e\n\n# Update a group — only the flags you pass change; other attributes are preserved\nkestractl groups update \u003cgroup_id\u003e --description 'Updated description'\nkestractl groups update \u003cgroup_id\u003e --name platform-admins\n\n# Set a user's group membership (replaces all current memberships in this group)\nkestractl groups set-membership \u003cgroup_id\u003e \u003cuser_id\u003e\n\n# Delete a group (alias: rm) — prompts for confirmation unless --yes\nkestractl groups delete \u003cgroup_id\u003e\nkestractl groups delete \u003cgroup_id\u003e --yes\n\n# Manage group members\nkestractl groups members list \u003cgroup_id\u003e\nkestractl groups members add \u003cgroup_id\u003e \u003cuser_id\u003e\nkestractl groups members remove \u003cgroup_id\u003e \u003cuser_id\u003e\n```\n\n### Roles (Enterprise Edition)\n\nRole management requires Kestra Enterprise Edition. Roles are tenant-scoped (the\nactive tenant is used).\n\nA role carries a `permissions` payload: a map of resource type (e.g. `FLOW`,\n`EXECUTION`, `NAMESPACE`, `SECRET`, `KVSTORE`, …) to a list of permission levels\n(`READ`, `CREATE`, `UPDATE`, `DELETE`). You can provide it inline with the\nrepeatable `--permission TYPE:LEVEL[,LEVEL]` flag, or from a YAML/JSON file with\n`--permissions-file` — but not both at once.\n\n```bash\n# List / filter roles (alias: ls)\nkestractl roles list\nkestractl roles list --query editor --output json\nkestractl roles list --page 1 --size 50 --sort name:asc\n\n# Get role details, including its permissions (aliases: show, describe)\nkestractl roles get \u003crole_id\u003e\n\n# Autocomplete role names\nkestractl roles autocomplete --query edi\n\n# Look up multiple roles by IDs\nkestractl roles list-from-ids \u003cid1\u003e \u003cid2\u003e\n\n# Create a role with inline permissions (--name is required, plus at least one permission)\nkestractl roles create --name editor \\\n  --description \"Can edit flows and view executions\" \\\n  --permission FLOW:READ,CREATE,UPDATE \\\n  --permission EXECUTION:READ\n\n# Create a role from a permissions file (YAML or JSON)\nkestractl roles create --name viewer --permissions-file perms.yaml\n\n# perms.yaml\n#   FLOW:\n#     - READ\n#   EXECUTION:\n#     - READ\n\n# Update a role — only the flags you pass change; other attributes are preserved.\n# Passing --permission replaces the entire permissions block (it does not merge).\nkestractl roles update \u003crole_id\u003e --description \"Updated description\"\nkestractl roles update \u003crole_id\u003e --permission FLOW:READ,CREATE,UPDATE,DELETE\nkestractl roles update \u003crole_id\u003e --default\n\n# Delete a role (alias: rm) — prompts for confirmation unless --yes\nkestractl roles delete \u003crole_id\u003e\nkestractl roles delete \u003crole_id\u003e --yes\n```\n\n### Service Accounts (Enterprise Edition)\n\nService account management requires Kestra Enterprise Edition. Service accounts\nare instance-level resources (command aliases: `service-account`, `sa`).\n\n\u003e `update` is a partial update of the name/description only. Tenant access,\n\u003e super-admin status and group membership are left untouched — set those at\n\u003e creation time.\n\n```bash\n# List service accounts (alias: ls)\nkestractl service-accounts list\nkestractl service-accounts list --output json\nkestractl service-accounts list --page 1 --size 50 --sort name:asc\n\n# Get service account details (aliases: show, describe)\nkestractl service-accounts get \u003cservice_account_id\u003e\n\n# Create a service account (--name is required; lowercase alphanumeric and dashes)\nkestractl service-accounts create --name ci-bot --description \"CI pipeline\"\n\n# Create a super-admin service account with tenant access (--tenant-grant is repeatable)\nkestractl service-accounts create --name ops-bot --superadmin --tenant-grant main\n\n# Update name/description — other attributes are preserved\nkestractl service-accounts update \u003cservice_account_id\u003e --description \"Updated description\"\nkestractl service-accounts update \u003cservice_account_id\u003e --name new-bot-name\n\n# Grant / revoke super-admin status\nkestractl service-accounts set-super-admin \u003cservice_account_id\u003e --superadmin\nkestractl service-accounts set-super-admin \u003cservice_account_id\u003e --superadmin=false\n\n# Delete a service account (alias: rm) — prompts for confirmation unless --yes\nkestractl service-accounts delete \u003cservice_account_id\u003e\nkestractl service-accounts delete \u003cservice_account_id\u003e --yes\n\n# Manage a service account's API tokens (the full token is shown only once, at creation)\nkestractl service-accounts tokens create \u003cservice_account_id\u003e --name deploy-token\nkestractl service-accounts tokens create \u003cservice_account_id\u003e --name short-lived --max-age P30D --extended\nkestractl service-accounts tokens list \u003cservice_account_id\u003e\nkestractl service-accounts tokens delete \u003cservice_account_id\u003e \u003ctoken_id\u003e\n```\n\n### Bindings (Enterprise Edition)\n\nIAM role bindings assign a role to a user, group, or service account within a tenant.\n\n```bash\n# List bindings (alias: ls)\nkestractl bindings list\nkestractl bindings list --output json\n\n# Get binding details (aliases: show, describe)\nkestractl bindings get \u003cbinding_id\u003e\n\n# Create a binding\nkestractl bindings create --role \u003crole_id\u003e --user \u003cuser_id\u003e\nkestractl bindings create --role \u003crole_id\u003e --group \u003cgroup_id\u003e\n\n# Create multiple bindings from a JSON file\nkestractl bindings bulk-create --file bindings.json\n\n# Delete a binding (alias: rm)\nkestractl bindings delete \u003cbinding_id\u003e\n```\n\n### Invitations (Enterprise Edition)\n\n```bash\n# List all invitations\nkestractl invitations list\nkestractl invitations list --output json\n\n# List invitations for a specific email address\nkestractl invitations list-by-email user@example.com\n\n# Get an invitation\nkestractl invitations get \u003cinvitation_id\u003e\n\n# Create an invitation\nkestractl invitations create --email user@example.com --role \u003crole_id\u003e\n\n# Delete an invitation (alias: rm)\nkestractl invitations delete \u003cinvitation_id\u003e\n```\n\n### Output Formats\n\n```bash\n# Table output (default, human-readable)\nkestractl flows list my.namespace\n\n# JSON output (for scripting)\nkestractl flows list my.namespace --output json\n```\n\n### Overriding Configuration\n\n```bash\n# Override config settings with flags\nkestractl flows get my.namespace my-flow \\\n  --host https://kestra.example.com \\\n  --tenant production \\\n  --token YOUR_TOKEN\n\n# Or use environment variables\nKESTRACTL_HOST=https://kestra.example.com \\\nKESTRACTL_TENANT=production \\\nKESTRACTL_TOKEN=YOUR_TOKEN \\\n  kestractl flows list my.namespace\n```\n\n## Architecture\n\nThe CLI uses a simple, direct architecture built on [Cobra](https://github.com/spf13/cobra), [Viper](https://github.com/spf13/viper), and the official Kestra Go SDK.\n\n```\nmain.go → root.go → commands → Client → Kestra SDK → Kestra API\n```\n\nConfiguration follows the [12-factor app](https://12factor.net/config) methodology:\n- Viper handles configuration from multiple sources (flags, env vars, config file)\n- Clear precedence order ensures predictable behavior\n- Flags are bound to Viper automatically via `PersistentPreRunE`\n\n### Project Structure\n\n```\nkestractl/\n├── main.go                        # Entrypoint - calls cli.Execute()\n├── go.mod                         # Dependencies: cobra, viper, kestra SDK, yaml\n└── src/cli/\n    ├── root.go                    # Root command, global flags, Viper initialization\n    ├── client.go                  # Client wrapper for SDK with Viper config resolution\n    ├── client_test.go\n    ├── auth.go                    # AuthManager - ~/.kestractl/config.yaml persistence\n    ├── auth_test.go\n    ├── render.go                  # Renderer: table or JSON output\n    ├── render_test.go\n    ├── telemetry.go               # PostHog event per command (disable via env var)\n    ├── telemetry_test.go\n    ├── config.go                  # Config subcommands (add, show, use, remove)\n    ├── flows.go                   # Flows commands\n    ├── flows_test.go\n    ├── executions.go              # Executions commands\n    ├── executions_test.go\n    ├── triggers.go                # Triggers commands\n    ├── triggers_test.go\n    ├── namespaces.go              # Namespaces commands\n    ├── namespaces_test.go\n    ├── kv.go                      # KV store commands (list, get, set, update, delete)\n    ├── kv_test.go\n    ├── nsfiles.go                 # Namespace files commands\n    ├── nsfiles_test.go\n    ├── plugins.go                 # Plugins commands (download, list)\n    ├── plugins_test.go\n    ├── workers.go                 # Workers commands (registration-tokens generate)\n    ├── workers_test.go\n    ├── dashboards.go              # Dashboards commands (EE)\n    ├── dashboards_test.go\n    ├── apps.go                    # Apps commands (EE)\n    ├── apps_test.go\n    ├── assets.go                  # Assets commands (EE)\n    ├── assets_test.go\n    ├── blueprints.go              # Blueprints commands (community + internal EE)\n    ├── blueprints_test.go\n    ├── test_suites.go             # Test suites commands (EE)\n    ├── test_suites_test.go\n    ├── users.go                   # IAM users commands (EE)\n    ├── users_test.go\n    ├── groups.go                  # IAM groups commands (EE)\n    ├── groups_test.go\n    ├── roles.go                   # IAM roles commands (EE)\n    ├── roles_test.go\n    ├── service_accounts.go        # IAM service accounts commands (EE)\n    ├── service_accounts_test.go\n    ├── bindings.go                # IAM role bindings commands (EE)\n    ├── bindings_test.go\n    ├── invitations.go             # IAM invitations commands (EE)\n    ├── invitations_test.go\n    └── testdata/                  # Test fixtures\n        └── flow.yaml\n```\n\n### Key Design Decisions\n\n| Decision | Rationale |\n|----------|-----------|\n| Direct SDK calls | No unnecessary abstraction layers. Commands call the SDK directly through a thin `Client` wrapper. |\n| 12-factor config with Viper | Viper handles flags \u003e env vars \u003e config file precedence automatically. Clean, predictable config resolution. |\n| YAML config format | Human-readable, supports multiple contexts, industry standard (similar to kubectl, docker, etc.). |\n| Pure functions for logic | Business logic in testable `run*()` functions separate from Cobra command wiring. |\n| Minimal test mocking | Tests focus on pure functions and argument validation. Integration tests for SDK calls. |\n\n## Development\n\n### Local Build\n\n```bash\ngo build ./...\n./kestractl --help\n```\n\n### Testing\n\n```bash\ngo test ./src/...\n```\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on adding new commands.\n\n## Requirements\n\n- Go 1.25 or newer\n- Access to a Kestra instance and API token\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestra-io%2Fkestractl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkestra-io%2Fkestractl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestra-io%2Fkestractl/lists"}