You are viewing the docs for v1.3, which is not the latest release.
View latest

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 .md to any kestra.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/kestra image.
  • 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 kestractl for 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 list

Global options

These options can be used with any Kestra CLI command.

  • -v, --verbose — Increase log verbosity (use -vv for 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 DEBUG

API 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:secret

kestra (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/flows

Point 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 properties

Flow commands

kestra flow validate

Validate a flow file.

Input: file (path)

bashkestra flow validate /path/to/my-flow.yml

kestra 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 value1

kestra 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.yml

kestra 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-directory

kestra 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-id

kestra 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-namespace

kestra flow namespace update

Update all flows within a namespace from a directory.

Option: --override-namespaces (optional)

bashkestra flow namespace update --override-namespaces /path/to/flows

kestra flow create

Create a new flow from a YAML file.

bashkestra flow create /path/to/new-flow.yml

kestra flow delete

Delete a flow.

Inputs: namespace, id

bashkestra flow delete my-namespace my-flow-id

Migration 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-run

Namespace 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 / --delete

kestra 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 1d

Plugin 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.3

kestra plugins uninstall

Uninstall one or more plugins.

bashkestra plugins uninstall io.kestra.plugin.jdbc:mysql:1.2.3

kestra plugins list

List installed plugins.

Option: --core to include core task plugins

bashkestra plugins list --core

kestra plugins doc

Generate documentation for installed plugins.

Inputs: output (default: ./docs) Options: --core, --icons, --schema

bashkestra plugins doc ./docs --core

Search for available plugins.

bashkestra plugins search jdbc

Server commands

kestra server executor

Start the executor.

Options: --ignore-executions (list)

bashkestra server executor

kestra server indexer

Start the indexer.

bashkestra server indexer

kestra server scheduler

Start the scheduler.

bashkestra server scheduler

kestra 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 standalone

kestra server webserver

Start the webserver.

Options:

  • --no-tutorials to disable auto-loading tutorials
  • --no-indexer to disable the embedded Indexer. Run kestra server indexer separately, since every deployment needs an Indexer.
bashkestra server webserver --no-tutorials

kestra server worker

Start a worker.

Options: -t, --thread (max threads), -g, --worker-group (EE only)

bashkestra server worker --thread 16

kestra server local

Start a local dev server.

bashkestra server local

Kestra 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_started

In production you might run a similar pattern either by:

  1. 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.
  2. 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 flow

kestra sys submit-queued-execution

Submit all queued executions to the executor.

bashkestra sys submit-queued-execution

kestra sys purge-queue

Available on:

v>=1.3.27Open Source EditionEnterprise Edition

Purge 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 PT1H

Rows 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 migrate

kestra sys state-store migrate

Migrate old state store files to the Key-Value (KV) Store.

bashkestra sys state-store migrate

Auths (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@123

kestra auths users create-basic-auth

Create or replace a basic auth password for a user.

bashkestra auths users create-basic-auth alice

kestra auths users refresh

Refresh users to update their properties.

bashkestra auths users refresh

kestra auths users set-superadmin

Set or remove Superadmin status.

Inputs: user, isSuperAdmin (true|false)

bashkestra auths users set-superadmin alice true

kestra auths users email-replace-username

Set the username as the email for every user.

bashkestra auths users email-replace-username

kestra auths users sync-access

Sync users' access with the fallback tenant (for enabling multi-tenancy).

bashkestra auths users sync-access

Backups (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-encryption

kestra 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.kestra

Systems (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 120

kestra 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-flows

kestra sys-ee reset-concurrency-limit

Resets the concurrency limit stored on the Kafka runner.

Inputs None

Example Usage

bashkestra-ee sys-ee reset-concurrency-limit

Tenants (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