Starting server components 11
The standalone JAR is itself the CLI: it is run as ./kestra-VERSION followed by the command, where the rows here write kestra.
| Command | What it does |
|---|---|
kestra server standalone | Start standalone serverRuns all core services in one process; it needs a configuration with a database connection. |
kestra server local | Start local dev serverLocal mode keeps its data in an H2 file database, so no external database is needed. |
kestra server local --config confs/application.yaml | Start with a config filePoints the server at a YAML configuration file; -c is the short form of the option. |
kestra server standalone --flow-path /path/to/flows | Preload flows at startupLoads every YAML flow in the folder at startup, each into the namespace its file declares; -f is the short form. |
kestra server webserver | Start the webserverRuns only the webserver, for deployments that split the components into separate services. |
kestra server webserver --no-tutorials | Start webserver without tutorialsStops the webserver from loading the tutorial flows automatically. |
kestra server executor | Start the executor |
kestra server worker | Start a worker |
kestra server worker --thread 16 | Start worker with thread capCaps the worker at 16 threads; -t is the short form of the option. |
kestra server scheduler | Start the scheduler |
kestra server indexer | Start the indexer |
Server command options 7
| Command | What it does |
|---|---|
-c, --config | Configuration file optionWorks with any command and takes the path of the configuration file to load. |
-p, --plugins | Plugins directory optionTells any command where the plugins directory is. |
-v, --verbose | Raise log verbosityWrite it as -vv for even more log output. |
-l, --log-level | Set the log levelAccepts TRACE, DEBUG, INFO, WARN or ERROR. |
--server URL | Target server addressFor commands that call the server API; the default is http://localhost:8080. |
--user USER:PASSWORD | Basic auth credentialsSigns API commands in with a user name and password pair. |
docker exec -it kestra /app/kestra plugins list | Run the CLI in DockerThe kestra/kestra image already contains the CLI, so any command can run through docker exec. |
Server-side flows and plugins 9
| Command | What it does |
|---|---|
kestra flow test /path/to/my-flow.yml myInput1 value1 | Run a flow locallyExecutes the file with the listed input key and value pairs; nothing is deployed to a server. |
kestra flow dot /path/to/my-flow.yml | Generate a DOT graphOutputs the flow structure in DOT format for a graph visualisation tool to draw. |
kestra flow export --namespace my-namespace /path/to/export-directory | Export flows to ZIPSaves the ZIP in the given directory; the namespace filter is optional. |
kestra flow delete my-namespace my-flow-id | Delete a flowTakes the namespace first and the flow ID second. |
kestra plugins install io.kestra.plugin.jdbc:mysql:1.2.3 | Install pluginsAccepts one or more plugins as Maven coordinates in group:artifact:version form. |
kestra plugins uninstall io.kestra.plugin.jdbc:mysql:1.2.3 | Uninstall plugins |
kestra plugins list --core | List installed pluginsWith --core the core task plugins are listed too. |
kestra plugins doc ./docs --core | Generate plugin documentationWrites documentation for the installed plugins into the output directory, ./docs by default. |
kestra plugins search jdbc | Search available plugins |
System maintenance 8
| Command | What it does |
|---|---|
kestra configs properties | Show effective configuration |
kestra sys reindex --type flow | Reindex flow recordsflow is currently the only record type that can be reindexed. |
kestra sys submit-queued-execution | Submit queued executionsHands every execution waiting in the queue over to the executor. |
kestra migrate plan | List pending migrationsRead-only: it takes no lock and writes nothing to the database. |
kestra migrate plan --sql | Show migration SQLAdds the raw SQL of every SQL-based migration to the plan output. |
kestra migrate run | Apply pending migrationsTakes a distributed lock first and exits with code 1 when another process holds it. |
kestra migrate unlock | Release the migration lockMeant for a lock left by an aborted run; does nothing on PostgreSQL, MySQL or H2. |
kestra namespace kv update my-ns my-key "my-value" -e 1d | Set a namespace KV key-e sets the expiration, one day here; -t gives the type and -f reads the value from a file. |
Flow commands of the 1.x server 5
At release tag v2.0.5 the open-source CLI registers only test, dot, delete, export and syncFromSource under kestra flow, so validate, update, updates and namespace update are not available there; on Kestra 2.0 use the kestractl flows commands.
At release tag v1.3.42 the flow group still registers the validate, namespace, update and updates subcommands that the kestra.io pages print.
| Command | What it does |
|---|---|
kestra flow validate /path/to/my-flow.yml | Validate a flow file |
kestra flow validate flows/ --server http://localhost:8080 | Validate a directory of flowsValidation runs server-side through the API unless --local is added to validate with the client. |
kestra flow namespace update namespace_name flows/ --no-delete --server http://localhost:8080 | Deploy flows to a namespace--no-delete keeps flows already stored; without it, flows missing from the directory are deleted. |
kestra flow update /path/to/my-updated-flow.yml my-namespace my-flow-id | Update a single flowReplaces one flow on the server from a local file, addressed by namespace and flow ID. |
kestra flow updates /path/to/my-flows --delete --namespace my-namespace | Bulk update flowsCreates or updates every flow in the directory; --delete removes server flows that are no longer there. |
kestractl setup and contexts 10
| Command | What it does |
|---|---|
curl -fsSL https://raw.githubusercontent.com/kestra-io/kestractl/main/install-scripts/install.sh | bash | Install kestractlInstalls the latest v3 release, which targets Kestra 2.x. |
docker run --rm ghcr.io/kestra-io/kestractl:latest --help | Run kestractl from DockerEach release also ships as a container image on Docker Hub and the GitHub registry. |
kestractl config add default http://localhost:8080 main --token YOUR_TOKEN --default | Add a token contextArguments are the context name, host and tenant; --default makes it the default context. |
kestractl config add default http://localhost:8080 main --username [email protected] --password YOUR_PASSWORD --default | Add a basic-auth contextStores a user name and password in the context where no API token is used. |
kestractl config show | List all contextsReads the contexts saved in ~/.kestractl/config.yaml. |
kestractl config use prod | Switch the default contextLater commands talk to the prod context until another one is selected. |
kestractl config remove dev | Remove a context |
kestractl flows list my.namespace --output json | Print JSON output--output, short -o, takes table or json on any command; table is the default. |
kestractl flows get my.namespace my-flow --host https://kestra.example.com --tenant production --token YOUR_TOKEN | Override context for one commandFlags take priority over environment variables, which in turn beat the config file. |
export KESTRACTL_HOST=http://localhost:8080 | Set host by environment variableKESTRACTL_TENANT and KESTRACTL_TOKEN work the same way and override the config file. |
Flows with kestractl 17
| Command | What it does |
|---|---|
kestractl flows list | List flows in all namespacesAdd a namespace argument to list only that namespace; ls is an alias. |
kestractl flows get my.namespace my-flow | Get a flow sourceshow and describe are aliases of get. |
kestractl flows deploy path/to/flow.yaml | Deploy one flow filecreate and apply are aliases of deploy. |
kestractl flows deploy ./flows/ | Deploy a directory of flowsWalks the directory recursively and deploys every flow it finds. |
kestractl flows deploy ./flows/ --namespace prod.namespace | Deploy into one namespaceEvery flow lands in the named namespace, whatever namespace its file declares. |
kestractl flows deploy ./flows/ --override | Overwrite existing flowsLets the deploy replace flows that already exist on the instance. |
kestractl flows deploy ./flows/ --fail-fast | Stop deploy on first errorThe deploy ends at the first flow that fails. |
kestractl flows validate ./flows/ | Validate a flow or directoryAccepts a single YAML file as well as a directory of flow files. |
kestractl flows validate-by-query --all | Validate stored flowsChecks flows already on the instance and exits non-zero when any has violations. |
kestractl flows export --namespace my.namespace --output-file flows.zip | Export flows to ZIPWrites the flows of the namespace into one ZIP archive. |
kestractl flows import flows.zip | Import flows from ZIP |
kestractl flows enable my.namespace my-flow | Enable a flow |
kestractl flows disable my.namespace my-flow | Disable a flow |
kestractl flows delete my.namespace my-flow | Delete a flow |
kestractl flows graph my.namespace my-flow --revision 3 --output json | Show flow topologyPrints the graph topology of a flow that is already deployed; --revision selects one revision. |
kestractl flows revisions my.namespace my-flow | List flow revisions |
kestractl flows namespace-sync my.namespace flows.yaml --delete --override | Sync a namespace from YAMLWith --delete, flows that the YAML file does not contain are removed from the namespace. |
Executions with kestractl 15
| Command | What it does |
|---|---|
kestractl executions run my.namespace my-flow | Run a flowtrigger and execute are aliases of run. |
kestractl executions run my.namespace my-flow --input branch=main --input dry_run=true | Run a flow with inputsRepeat --input once for each key=value pair the flow expects. |
kestractl executions run my.namespace my-flow --wait | Run and wait for completionBlocks until the execution has finished. |
kestractl executions list --namespace my.namespace --flow my-flow | List executionsThe two flags narrow the list to one namespace and one flow. |
kestractl executions get 2TLGqHrXC9k8BczKJe5djX | Show execution detailsshow and describe work as aliases. |
kestractl executions watch 2TLGqHrXC9k8BczKJe5djX | Watch an execution liveFollows the run as it happens and exits non-zero on failure; follow is an alias. |
kestractl executions kill 2TLGqHrXC9k8BczKJe5djX | Kill an execution |
kestractl executions pause 2TLGqHrXC9k8BczKJe5djX | Pause an execution |
kestractl executions resume 2TLGqHrXC9k8BczKJe5djX | Resume an execution |
kestractl executions restart 2TLGqHrXC9k8BczKJe5djX | Restart an execution |
kestractl executions replay 2TLGqHrXC9k8BczKJe5djX | Replay an execution |
kestractl executions set-labels 2TLGqHrXC9k8BczKJe5djX env=prod team=platform | Label an executionTakes one or more key=value labels after the execution ID. |
kestractl executions kill-by-query --namespace my.namespace --flow my-flow | Kill executions by queryBulk form that kills every execution matching the namespace and flow filters. |
kestractl executions download-file 2TLGqHrXC9k8BczKJe5djX --path outputs/result.csv | Download an output file--path names the output file of the execution to fetch. |
kestractl executions delete 2TLGqHrXC9k8BczKJe5djX | Delete an execution |
Namespaces and namespace files 14
In kestractl v3.6.0 the upload destination is the third positional argument, after the namespace and the local path.
| Command | What it does |
|---|---|
kestractl namespaces list | List namespacesls is an alias, and --query filters the list. |
kestractl namespaces get my.namespace | Show namespace details |
kestractl namespaces create my.namespace | Create a namespace |
kestractl namespaces update my.namespace --description "Production namespace" | Update a namespaceChanges the description stored for an existing namespace. |
kestractl namespaces delete my.namespace | Delete a namespace |
kestractl namespaces create my.namespace --variable env=prod --variable region=eu | Create namespace with variables--variable is repeatable and replaces the whole variable set of the namespace. |
kestractl nsfiles list my.namespace | List namespace filesLists the files at the namespace root; ls is an alias. |
kestractl nsfiles list my.namespace --path workflows/ --recursive | List a directory recursively |
kestractl nsfiles get my.namespace workflows/example.yaml | Print the content of a fileOutputs the raw content of the file; cat is an alias. |
kestractl nsfiles upload my.namespace ./local.txt workflows/local.txt | Upload a single fileArguments are the namespace, the local path and the destination path. |
kestractl nsfiles upload my.namespace ./assets resources | Upload a directoryUploads the directory recursively to the given path in the namespace. |
kestractl nsfiles upload my.namespace ./assets resources --override | Overwrite files on uploadReplaces files that already exist at the destination. |
kestractl nsfiles delete my.namespace workflows/example.yaml | Delete a namespace file |
kestractl nsfiles delete my.namespace workflows --recursive | Delete a directory recursively |
Key-value store, logs and plugins 12
| Command | What it does |
|---|---|
kestractl kv list my.namespace | List namespace keysNeeds token authentication; with basic auth the request returns 401. |
kestractl kv set my.namespace STRING api_key "my-secret" | Set a key-value pairArguments are namespace, type, key and value; types include STRING, NUMBER, BOOLEAN and JSON. |
kestractl kv set my.namespace STRING session_token "abc" --ttl PT1H | Set an expiring keyThe TTL is an ISO 8601 duration, one hour in this example. |
kestractl kv update my.namespace NUMBER retries 5 | Update an existing keyFails when the key has not been set before. |
kestractl kv get my.namespace api_key | Read a keyShows the type of the key together with its value. |
kestractl kv delete my.namespace api_key | Delete a keyThe alias rm does the same as delete. |
kestractl logs list EXECUTION_ID | List execution logs--min-level and --task-id narrow the entries that are returned. |
kestractl logs search --namespace my.namespace --flow-id my-flow --min-level ERROR | Search logs across executionsFinds log entries of one flow at ERROR level or above. |
kestractl logs download EXECUTION_ID --output-file execution.log | Download execution logsSaves the logs of one execution to the named file. |
kestractl plugins list 2.0.0 | List compatible pluginsPrints the coordinates of all plugins compatible with that Kestra version on one line. |
kestractl plugins download 1.3.9 | Download plugins for a versionFetches every plugin JAR for that Kestra version into ./plugins. |
kestractl plugins get io.kestra.plugin:plugin-kafka:1.6.0 | Download a single pluginFetches one plugin JAR identified by its exact Maven coordinates. |
No row on this page matches that filter.
Notes
Two CLIs, one platform
Kestra ships two distinct command-line tools, and knowing which is which saves real confusion. The classic kestra binary is the server CLI: it is the same executable that runs the server components (kestra server standalone starts all core services in one process, kestra server local uses an H2 file database for development), installs plugins into the runtime and runs maintenance such as database migrations. kestractl is the Go-based client: it talks to a running server’s API and manages flows, executions, namespaces, namespace files and key-value pairs from anywhere. In short — server, process and database operations go to kestra, API-level resource management goes to kestractl.
The deployment loop
A typical release runs four commands. kestractl flows validate ./flows/ checks every YAML file; kestractl flows deploy ./flows/ --namespace prod.namespace pushes them into one namespace, with --override and --fail-fast for strictness; kestractl executions run my.namespace my-flow --wait fires a smoke-test flow and blocks until it finishes; and kestractl executions watch 2TLGqHrXC9k8BczKJe5djX, given a real execution ID, follows the run live and exits non-zero on failure — which makes it a natural CI gate with no extra scripting. Older pipelines did the first two steps with the server CLI, kestra flow validate /path/to/my-flow.yml and kestra flow namespace update namespace_name flows/ --no-delete --server http://localhost:8080. The CI/CD guide still prints both, but the open-source CLI source registers them in the 1.3 line only, not at tag v2.0.5. On 1.x, note that namespace update deletes flows missing from the directory unless --no-delete is passed.
Everything is scriptable
Every kestractl command accepts the global --output flag, as in kestractl flows list my.namespace --output json, which turns the CLI into a query tool for scripts: list flows, pull an execution’s state, or read a key-value pair. Execution control covers the whole lifecycle without touching the UI — pause, resume, restart, replay and kill each take an execution ID, and the -by-query variants act on every execution a filter matches. Authentication lives in named contexts created by kestractl config add default http://localhost:8080 main --token YOUR_TOKEN --default (an API token, or --username and --password for basic auth), so switching between a local instance and production is kestractl config use prod, and command-line flags or KESTRACTL_ environment variables override the stored context for a single run.
Questions
What is the difference between kestra and kestractl?
kestra is the server CLI: the same executable that runs the server components, and it also handles plugins, system maintenance and database migrations. kestractl is the API client for daily work on flows, executions, namespaces, namespace files and key-value pairs. Use kestra for the machine, kestractl for the resources.
How do I start Kestra in one process?
kestra server standalone starts all core services together and needs a configuration with a database connection. For development, kestra server local runs with an H2 local file database, so no external database is required.
How do I deploy Kestra flows from CI/CD?
Validate with kestractl flows validate ./flows/, then deploy with kestractl flows deploy ./flows/ --namespace prod.namespace. The server CLI equivalents, kestra flow validate and kestra flow namespace update, belong to the 1.x line: the open-source CLI source at tag v2.0.5 no longer registers them. On 1.x, namespace update deletes flows absent from the directory unless --no-delete is passed.
Can the Kestra CLI wait for a flow to finish?
Yes, two ways: kestractl executions run my.namespace my-flow --wait blocks until completion, and kestractl executions watch 2TLGqHrXC9k8BczKJe5djX, with a real execution ID in place of the sample, follows an execution live and exits non-zero on failure — handy as a CI gate.
Why does my standalone Kestra JAR fail on tasks?
The standalone JAR ships without plugins. Install them with kestra plugins install io.kestra.plugin.jdbc:mysql:1.2.3, where the argument is the plugin’s Maven coordinates, or in local mode let Kestra install missing plugins the first time a flow needs them by setting KESTRA_PLUGINS_AUTO_INSTALL_ENABLED=true.
How does kestractl authenticate?
Through named contexts: kestractl config add default http://localhost:8080 main --token YOUR_TOKEN --default stores the host, tenant and credentials in ~/.kestractl/config.yaml. A context holds either an API token or a --username and --password pair; the default context applies automatically, and flags or KESTRACTL_ environment variables override it.
Which kestractl release works with Kestra 1.x?
kestractl v3 targets Kestra 2.x and still works against Kestra 1.3 for everyday commands on flows, executions, namespace files, the key-value store and namespaces. For the full 1.x feature set its README points to the latest v1 release instead.
Sources and checks
- Kestra Docs: Server CLI in Kestra, Commands and Options (kestra.io, current edition covering Kestra 2.0) kestra server CLI: server components, global and API options, flow, plugins, sys, migrate and namespace commands
- kestractl README, release tag v3.6.0 (kestra-io/kestractl on GitHub) kestractl installation, contexts, flows, executions, namespaces, namespace files, key-value store and plugin downloads
- Kestra Docs: kestractl, Kestra CLI for Flows, IAM, and Plugins (kestra.io) kestractl logs commands, kv list and plugins list
- Kestra Docs: Run from Standalone JAR in Kestra (kestra.io) server local, the --config option and how the standalone JAR is invoked
- Kestra Docs: CI/CD Pipelines in Kestra, Validate and Deploy Flows (kestra.io) kestra flow validate and kestra flow namespace update with --no-delete and --server
- Kestra source, release tag v2.0.5: FlowCommand.java (kestra-io/kestra on GitHub) subcommands the open-source 2.0.5 server CLI registers under kestra flow
- Kestra source, release tag v1.3.42: FlowCommand.java (kestra-io/kestra on GitHub) subcommands the open-source 1.3.42 server CLI registers under kestra flow
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.