Kestra Server CLI Reference: All Commands and Options

Table of Contents

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:

# 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

kestra 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 and Cloud only).
--api-token — API token (EE and Cloud only).

Examples

kestra flow list --server http://my-kestra:8080
kestra flow list --user admin:secret

`kestra` (top-level)

Usage: 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
  sys        handle systems maintenance
  configs    handle configs
  namespace  handle namespaces
  auths      handle auths
  tenants    handle tenants
  migrate    handle migrations
  backups    (EE) handle metadata backups and restore

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:

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

kestra configs properties

Flow commands

`kestra flow validate`

Validate a flow file.

Input: file (path)

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

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

kestra flow dot /path/to/my-flow.yml

`kestra flow export`

Export flows to a ZIP file.

Inputs: --namespace (optional), directory (path to export into)

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

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

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

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

`kestra flow create`

Create a new flow from a YAML file.

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

`kestra flow delete`

Delete a flow.

Inputs: namespace, id

kestra flow delete my-namespace my-flow-id

Migration commands

`kestra migrate plan`

Lists all pending database migrations without applying them. Read-only: acquires no lock, writes nothing.

Options: --sql (print the raw SQL for each SQL-based migration)

kestra migrate plan
kestra migrate plan --sql

`kestra migrate run`

Applies all pending migrations in lexicographic order. Acquires a distributed lock so only one process migrates at a time. Makes a single non-blocking lock attempt; if the lock is already held, exits immediately with code 1.

kestra migrate run

Enterprise Edition users must run this command manually before starting Kestra 2.0 for the first time. By default (kestra.migration.auto=false), Kestra EE refuses to start if any pending migrations exist. Open-source Kestra runs migrations automatically on startup.

`kestra migrate unlock`

Force-releases the migration lock. Use only when kestra migrate run exited abnormally and left the lock held.

kestra migrate unlock

On PostgreSQL, MySQL, and H2, the lock is session-scoped. kestra migrate unlock always exits 0 but does nothing on these backends. The lock releases when the holding process terminates. Kill the hung process instead. On Elasticsearch, the command works as expected.

`kestra migrate default-tenant`

Migrate all resources without a tenant to a new tenant (multi-tenant setups).

Options: --tenant-id, --tenant-name, --dry-run

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

kestra 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

kestra 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

kestra plugins install io.kestra.plugin.jdbc:mysql:1.2.3

`kestra plugins uninstall`

Uninstall one or more plugins.

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

`kestra plugins list`

List installed plugins.

Option: --core to include core task plugins

kestra plugins list --core

`kestra plugins doc`

Generate documentation for installed plugins.

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

kestra plugins doc ./docs --core

`kestra plugins search`

Search for available plugins.

kestra plugins search jdbc

Server commands

`kestra server executor`

Start the executor.

Options: --ignore-executions (list)

kestra server executor

`kestra server indexer`

Start the indexer.

kestra server indexer

`kestra server scheduler`

Start the scheduler.

kestra server scheduler

`kestra server standalone`

Start a standalone server (all core services).

kestra server standalone

`kestra server webserver`

Start the webserver.

Option: --no-tutorials to disable auto-loading tutorials

kestra server webserver --no-tutorials

`kestra server worker`

Start a worker.

Options: -t, --thread (max threads)

kestra server worker --thread 16

`kestra server local`

Start a local dev server.

kestra server local

Kestra with server components in different services

Server components run independently from each other. Most communicate through the queue layer; Workers communicate with the Worker Controller over a bidirectional gRPC stream and never connect to the database directly.

Below is an example Docker Compose configuration file running Kestra services with replicas on the PostgreSQL database backend.

Docker Compose Example

volumes:
  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:

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

kestra sys reindex --type flow

`kestra sys submit-queued-execution`

Submit all queued executions to the executor.

kestra sys submit-queued-execution

`kestra sys database migrate`

Force database schema migration (Flyway).

kestra sys database migrate

`kestra sys state-store migrate`

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

kestra sys state-store migrate

Auths (EE)

`kestra auths users create`

Create a user.

Inputs: username (required), password (optional) Options: --groups, --tenant, --admin, --instance-owner, --if-not-exists

--superadmin is a deprecated alias for --instance-owner and still works.

kestra auths users create --instance-owner --tenant=default admin Admin_password@123

`kestra auths users create-basic-auth`

Create or replace a basic auth password for a user.

kestra auths users create-basic-auth alice

`kestra auths users refresh`

Refresh users to update their properties.

kestra auths users refresh

`kestra auths users set-instance-owner`

Set or remove Instance Owner status.

Inputs: user, instanceOwner (true|false)

kestra auths users set-instance-owner alice true

set-superadmin is a deprecated alias for set-instance-owner and still works.

`kestra auths users email-replace-username`

Set the username as the email for every user.

kestra auths users email-replace-username

`kestra auths users sync-access`

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

kestra 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, --resources

kestra backups create FULL --no-encryption

`kestra backups restore`

Restore a metadata backup.

Input: uri (Kestra internal storage URI) Options: --encryption-key, --to-tenant, --resources

kestra backups restore kestra:///backups/full/backup-20240917163312.kestra

Tenants (EE)

`kestra tenants create`

Create a tenant and assign admin roles to an existing admin user.

Inputs: tenantId, tenantName Option: --admin-username

kestra tenants create tenantA "Tenant A" --admin-username alice

kestractlkestractl: Kestra CLI for Flows, IAM, and Plugins

Was this page helpful?

Kestra Server CLI Reference: All Commands and Options

Use the Kestra server CLI effectively

Installation

Global options

API options

kestra (top-level)

Preload flows at startup

Configuration commands

kestra configs properties

Flow commands

kestra flow validate

kestra flow test

kestra flow dot

kestra flow export

kestra flow update

kestra flow updates

kestra flow namespace update

kestra flow create

kestra flow delete

Migration commands

kestra migrate plan

kestra migrate run

kestra migrate unlock

kestra migrate default-tenant

Namespace commands

kestra namespace files update

kestra namespace kv update

Plugin commands

kestra plugins install

kestra plugins uninstall

kestra plugins list

kestra plugins doc

kestra plugins search