Kestra Server CLI Reference: All Commands and Options
For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append.mdto anykestra.io/docs/*URL for plain Markdown.
Use kestra to interact with the Kestra server and database
Use the Kestra server CLI effectively
This page includes CLI commands and options for both Open Source and Enterprise editions. Enterprise-only operations are marked with (EE) where relevant.
Installation
The Kestra Server CLI (kestra) is not a separate tool to install. It is the same executable used to run Kestra server components, so you get it through your Kestra installation method.
- Docker / Docker Compose / Kubernetes: the CLI is already included in the
kestra/kestraimage. - Standalone JAR: the downloaded executable (
./kestra-VERSION) is the CLI. - Managed environments (e.g. Kestra Cloud): host-level server commands are typically not available. Use
kestractlfor API-level operations.
To install Kestra first, follow one of these guides:
Examples of the same CLI in each mode:
bash# Docker container
docker exec -it kestra /app/kestra plugins list
# Standalone binary
./kestra-VERSION plugins listGlobal options
These options can be used with any Kestra CLI command.
-v, --verbose— Increase log verbosity (use-vvfor more).-l, --log-level— Set a specific level:TRACE,DEBUG,INFO,WARN,ERROR.--internal-log— Also change the level for internal logs.-c, --config— Path to a configuration file (default:~/.kestra/config.yml).-p, --plugins— Path to the plugins directory.
Examples
bashkestra plugins list -vv
kestra plugins install --log-level DEBUGAPI options
Available for commands that talk to the server API.
--server— Kestra server URL (default:http://localhost:8080).--headers— Add custom headers (<name=value>).--user— Basic auth (user:password).--tenant— Tenant identifier (EE only).--api-token— API token (EE only).
Examples
bashkestra flow list --server http://my-kestra:8080
kestra flow list --user admin:secretkestra (top-level)
bashUsage: kestra [-hV] [COMMAND]
Options:
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
plugins handle plugins
server handle servers
flow handle flows
template handle templates
sys handle systems maintenance
configs handle configs
namespace handle namespaces
auths handle auths
sys-ee handle kestra ee systems maintenance
tenants handle tenants
migrate handle migrations
backups (EE) handle metadata backups and restore
server start Kestra servers (see `--flow-path` below for preloading flows)Preload flows at startup
Use the --flow-path (or -f) flag to load all flows from a directory when starting Kestra so they’re available immediately:
bashkestra server standalone --flow-path /path/to/flowsPoint this to a folder of YAML flow definitions; Kestra will load them at startup into the namespaces declared in each file.
Configuration commands
kestra configs properties
Display the effective configuration properties.
bashkestra configs propertiesFlow commands
kestra flow validate
Validate a flow file.
Input: file (path)
bashkestra flow validate /path/to/my-flow.ymlkestra flow test
Run a flow locally with specific inputs, helping you test its logic without deploying it to the server.
Inputs: file (path), inputs (key value pairs; absolute path for file inputs)
bashkestra flow test /path/to/my-flow.yml myInput1 value1kestra flow dot
Generate a DOT graph from a flow file, which you can use with a visualization tool to create a visual diagram of your flow's structure.
bashkestra flow dot /path/to/my-flow.ymlkestra flow export
Export flows to a ZIP file.
Inputs: --namespace (optional), directory (path to export into)
bashkestra flow export --namespace my-namespace /path/to/export-directorykestra flow update
Update a single flow on the server from a local file. You must specify the flow's namespace and its unique ID.
Inputs: flowFile (path), namespace (string), id (string)
bashkestra flow update /path/to/my-updated-flow.yml my-namespace my-flow-idkestra flow updates
Bulk update flows from a directory. Point the command to a directory, and Kestra will create or update all the flows it finds. The --delete flag removes any flows on the server that are no longer in the specified directory.
Inputs: directory (path), --delete (optional), --namespace (optional)
bashkestra flow updates /path/to/my-flows --delete --namespace my-namespacekestra flow namespace update
Update all flows within a namespace from a directory.
Option: --override-namespaces (optional)
bashkestra flow namespace update --override-namespaces /path/to/flowskestra flow create
Create a new flow from a YAML file.
bashkestra flow create /path/to/new-flow.ymlkestra flow delete
Delete a flow.
Inputs: namespace, id
bashkestra flow delete my-namespace my-flow-idMigration commands
kestra migrate default-tenant
Migrate all resources without tenant to a new tenant (multi-tenant setups).
Options: --tenant-id, --tenant-name, --dry-run
bashkestra migrate default-tenant --tenant-id my-tenant --tenant-name "My Tenant" --dry-runNamespace commands
kestra namespace files update
Sync namespace files from a local directory.
Inputs: namespace, from (local path), to (remote path, default /), --delete (optional)
bashkestra namespace files update my-namespace /path/to/local/files / --deletekestra namespace kv update
Set/update a key in the namespace KV store. Set an expiration time, specify the data type, and even read the value from a file.
Inputs: namespace, key, value
Options: -e, --expiration, -t, --type, -f, --file-value
bashkestra namespace kv update my-ns my-key "my-value" -e 1dPlugin commands
kestra plugins install
Install one or more plugins by Maven coordinates.
Options: --locally (default true), --all, --repositories
bashkestra plugins install io.kestra.plugin.jdbc:mysql:1.2.3kestra plugins uninstall
Uninstall one or more plugins.
bashkestra plugins uninstall io.kestra.plugin.jdbc:mysql:1.2.3kestra plugins list
List installed plugins.
Option: --core to include core task plugins
bashkestra plugins list --corekestra plugins doc
Generate documentation for installed plugins.
Inputs: output (default: ./docs)
Options: --core, --icons, --schema
bashkestra plugins doc ./docs --corekestra plugins search
Search for available plugins.
bashkestra plugins search jdbcServer commands
kestra server executor
Start the executor.
Options: --ignore-executions (list)
bashkestra server executorkestra server indexer
Start the indexer.
bashkestra server indexerkestra server scheduler
Start the scheduler.
bashkestra server schedulerkestra server standalone
Start a standalone server (all core services).
Option: --no-indexer to disable the embedded Indexer. Run kestra server indexer separately, since every deployment needs an Indexer.
bashkestra server standalonekestra server webserver
Start the webserver.
Options:
--no-tutorialsto disable auto-loading tutorials--no-indexerto disable the embedded Indexer. Runkestra server indexerseparately, since every deployment needs an Indexer.
bashkestra server webserver --no-tutorialskestra server worker
Start a worker.
Options: -t, --thread (max threads), -g, --worker-group (EE only)
bashkestra server worker --thread 16kestra server local
Start a local dev server.
bashkestra server localKestra with server components in different services
Server components can run independently from each other. Each of them communicate through the database.
Below is an example Docker Compose configuration file running Kestra services with replicas on the PostgreSQL database backend.
Docker Compose Example
yamlvolumes:
postgres-data:
driver: local
kestra-data:
driver: local
services:
postgres:
image: postgres
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
POSTGRES_DB: kestra
POSTGRES_USER: kestra
POSTGRES_PASSWORD: k3str4
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
interval: 30s
timeout: 10s
retries: 10
kestra-scheduler:
image: kestra/kestra:latest
deploy:
replicas: 2
pull_policy: if_not_present
user: "root"
command: server scheduler
volumes:
- kestra-data:/app/storage
- /var/run/docker.sock:/var/run/docker.sock
- /tmp/kestra-wd:/tmp/kestra-wd
environment:
KESTRA_CONFIGURATION: &common_configuration |
datasources:
postgres:
url: jdbc:postgresql://postgres:5432/kestra
driver-class-name: org.postgresql.Driver
username: kestra
password: k3str4
kestra:
server:
basic-auth:
enabled: false
username: "admin@kestra.io"
password: kestra
repository:
type: postgres
storage:
type: local
local:
base-path: "/app/storage"
queue:
type: postgres
tasks:
tmp-dir:
path: /tmp/kestra-wd/tmp
ports:
- "8082-8083:8081"
depends_on:
postgres:
condition: service_started
kestra-worker:
image: kestra/kestra:latest
deploy:
replicas: 2
pull_policy: if_not_present
user: "root"
command: server worker
volumes:
- kestra-data:/app/storage
- /var/run/docker.sock:/var/run/docker.sock
- /tmp/kestra-wd:/tmp/kestra-wd
environment:
KESTRA_CONFIGURATION: *common_configuration
ports:
- "8084-8085:8081"
depends_on:
postgres:
condition: service_started
kestra-executor:
image: kestra/kestra:latest
deploy:
replicas: 2
pull_policy: if_not_present
user: "root"
command: server executor
volumes:
- kestra-data:/app/storage
- /var/run/docker.sock:/var/run/docker.sock
- /tmp/kestra-wd:/tmp/kestra-wd
environment:
KESTRA_CONFIGURATION: *common_configuration
ports:
- "8086-8087:8081"
depends_on:
postgres:
condition: service_started
kestra-webserver:
image: kestra/kestra:latest
deploy:
replicas: 1
pull_policy: if_not_present
user: "root"
command: server webserver
volumes:
- kestra-data:/app/storage
- /var/run/docker.sock:/var/run/docker.sock
- /tmp/kestra-wd:/tmp/kestra-wd
environment:
KESTRA_CONFIGURATION: *common_configuration
KESTRA_URL: http://localhost:8080/
ports:
- "8080:8080"
- "8081:8081"
depends_on:
postgres:
condition: service_startedIn production you might run a similar pattern either by:
- Running Kestra services on dedicated machines. For examples, running the webserver, the scheduler, and the executor on one VM and running one or more workers on other instances.
- Using Kubernetes and Helm charts. Read more about how to set these up in the Kubernetes installation documentation.
System commands
kestra sys reindex
Reindex records (currently only flow).
Option: --type
bashkestra sys reindex --type flowkestra sys submit-queued-execution
Submit all queued executions to the executor.
bashkestra sys submit-queued-executionkestra sys purge-queue
Available on:
v>=1.3.27Open Source EditionEnterprise EditionPurge expired rows from the JDBC queues table, using the JDBC cleaner retention, without starting any server component. Use it to recover an instance whose executor can no longer purge the queue on its own. On MySQL, rows are deleted in batches to avoid long locks.
Option: --retention overrides the global retention for this run, as an ISO 8601 duration. Retentions configured for specific queue types still apply.
bashkestra sys purge-queue --retention PT1HRows that no consumer has read are kept. The command only works with a JDBC queue (H2, MySQL, or PostgreSQL).
kestra sys database migrate
Force database schema migration (Flyway).
bashkestra sys database migratekestra sys state-store migrate
Migrate old state store files to the Key-Value (KV) Store.
bashkestra sys state-store migrateAuths (EE)
kestra auths users create
Create a user.
Inputs: username (required), password (optional)
Options: --groups, --tenant, --admin, --superadmin, --if-not-exists
bashkestra auths users create --superadmin --tenant=default admin Admin_password@123kestra auths users create-basic-auth
Create or replace a basic auth password for a user.
bashkestra auths users create-basic-auth alicekestra auths users refresh
Refresh users to update their properties.
bashkestra auths users refreshkestra auths users set-superadmin
Set or remove Superadmin status.
Inputs: user, isSuperAdmin (true|false)
bashkestra auths users set-superadmin alice truekestra auths users email-replace-username
Set the username as the email for every user.
bashkestra auths users email-replace-usernamekestra auths users sync-access
Sync users' access with the fallback tenant (for enabling multi-tenancy).
bashkestra auths users sync-accessBackups (EE)
kestra backups create
Create a metadata backup.
Inputs: type (FULL | TENANT)
Options: --tenant, --encryption-key, --no-encryption, --include-data
bashkestra backups create FULL --no-encryptionkestra backups restore
Restore a metadata backup.
Input: uri (Kestra internal storage URI)
Options: --encryption-key, --to-tenant
bashkestra backups restore kestra:///backups/full/backup-20240917163312.kestraSystems (EE)
kestra sys-ee restore-flow-listeners
Restores the state-store for FlowListeners. Useful after restoring a flow queue.
Inputs
--timeout(option): Timeout in seconds before quitting (default: 60).
Example Usage
bashkestra-ee sys-ee restore-flow-listeners --timeout 120kestra sys-ee restore-queue
Sends all data from a repository to Kafka. Useful for restoring all resources after a backup.
Inputs
--no-recreate(option): Don't drop and recreate the Kafka topic.--no-flows(option): Don't send flows.--no-templates(option): Don't send templates.
Example Usage
bashkestra-ee sys-ee restore-queue --no-flowskestra sys-ee reset-concurrency-limit
Resets the concurrency limit stored on the Kafka runner.
Inputs None
Example Usage
bashkestra-ee sys-ee reset-concurrency-limitTenants (EE)
kestra tenants create
Create a tenant and assign admin roles to an existing admin user.
Inputs: tenantId, tenantName
Option: --admin-username
bashkestra tenants create tenantA "Tenant A" --admin-username alice