Replace Removed kestra flow Commands with kestractl
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.
Available on:Open Source EditionEnterprise Edition
Kestra 2.0 removes the server CLI commands that validated, created, and updated flows and namespace files through the Kestra API. Use kestractl, the command-line client for the Kestra API, instead.
CI/CD pipelines that run these commands, for example /app/kestra flow validate or kestra flow namespace update in the kestra/kestra image, fail on 2.0 because the commands no longer exist.
Replacement commands
| Removed command | Replacement |
|---|---|
kestra flow validate <path> | kestractl flows validate <path> |
kestra flow create <file> | kestractl flows deploy <file> |
kestra flow update <file> <namespace> <id> | kestractl flows deploy <file> --override |
kestra flow updates <directory> | kestractl flows deploy <directory> --override |
kestra flow namespace update <namespace> <directory> | kestractl flows deploy <directory> --namespace <namespace> --override |
kestra namespace files update <namespace> <directory> <path> | kestractl nsfiles upload <namespace> <directory> <path> --no-root --override |
kestra flow expand <file> | None. See Include helpers. |
kestractl flows deploy never deletes flows. If a pipeline relied on the old commands deleting flows that were missing from the directory, use kestractl flows namespace-sync with --delete.
The server CLI commands that run Kestra itself, such as kestra server standalone, kestra flow test, and kestra migrate, are unchanged. See Kestra Server CLI.
Migration steps
- Find every pipeline and script that calls
kestra floworkestra namespace files, for example/app/kestra flow ...in akestra/kestracontainer. - Replace each command with its
kestractlequivalent from the table above. - Replace the
--server,--api-token,--user, and--tenantoptions withKESTRACTL_HOST,KESTRACTL_TOKEN,KESTRACTL_USERNAMEandKESTRACTL_PASSWORD, andKESTRACTL_TENANTenvironment variables. In CI, store the token and password as masked secrets. - Run the pipeline in the
kestra/kestractlimage instead ofkestra/kestra.
Before
/app/kestra flow validate flows/ --server https://kestra.example.com --api-token $KESTRA_API_TOKEN/app/kestra flow namespace update prod flows/ --server https://kestra.example.com --api-token $KESTRA_API_TOKENAfter
export KESTRACTL_HOST=https://kestra.example.comexport KESTRACTL_TOKEN=$KESTRA_API_TOKENkestractl flows validate flows/kestractl flows deploy flows/ --namespace prod --override --fail-fastFor complete pipeline examples, see GitLab CI and Bitbucket Pipes.
Include helpers
The [[> file]] include helper, which inserted the content of a local file into a flow when the CLI expanded it before upload, is removed along with kestra flow expand and kestra flow validate --local. kestractl deploys flow files as they are, so a flow that still contains [[> file]] is deployed with that text unchanged.
To keep long scripts or SQL out of the flow YAML, store them as namespace files and reference them at runtime:
- Read a file into a property with the
read()function, for examplesql: "{{ read('queries/report.sql') }}". - For script tasks, enable
namespaceFilesand run the file directly, for examplepython scripts/etl.py.
Upload the files from CI with kestractl nsfiles upload. The namespace must already exist; create it first with kestractl namespaces create if needed.
Was this page helpful?