How-to Guides¶

Setting up the sandbox in the Quick Start section was easy; building a production-grade environment requires a bit more work!

These how-to guides will step you through common tasks in using and configuring an airflowctl environment.

How to use airflowctl¶

Important Note¶

airflowctl needs the Airflow API running to be able to work. Please, see the login section below before use. Otherwise, you may get errors.

Datetime Usage¶

For datetime parameters, date should be timezone aware and in ISO format. For example: 2025-10-10T10:00:00+00:00 Let’s take example of triggering a DAG run with a logical date, run after and a note.

airflowctl dagrun trigger --dag-id="example_bash_operator" --logical-date="2025-09-06T00:00:00+00:00" --run-after="2025-09-06T00:00:00+00:00" --note="Triggered from airflowctl"

Login¶

airflowctl needs to be able to connect to the Airflow API. You should pass API URL as a parameter to the command --api-url. The URL should be in the form of http(s)://<host>:<port>. You can also set the environment variable AIRFLOW_CLI_TOKEN to the token to use for authentication.

There are two ways to authenticate with the Airflow API: 1. Using a token acquired from the Airflow API

airflowctl auth login --api-url <api_url> --api-token <token> --env <env_name:production>

Using a username and password

airflowctl auth login --api-url <api_url> --username <username> --password <password> --env <env_name:production>

(optional) Using a token acquired from the Airflow API and username and password

export AIRFLOW_CLI_TOKEN=<token>
airflowctl auth login --api-url <api_url> --env <env_name>

In both cases token is securely stored in the keyring backend. Only configuration persisted in ~/.config/airflow file is the API URL and the environment name. The token is stored in the keyring backend and is not persisted in the configuration file. The keyring backend is used to securely store the token and is not accessible to the user.

What is authentication for `airflowctl`?¶

For airflowctl to be able to communicate with the Airflow API, it needs to authenticate itself and acquire token. This is done using either a token or a username and password. The token can be acquired from the Airflow API or generated using a username and password.

Parameter Details for airflowctl auth login¶

–api-url: This parameter is required. (e.g. http://localhost:8080) The default value is http://localhost:8080. Full URL of the Airflow API. Without any /api/* suffixes. If you are running the airflowctl in breeze container, it is optional.

–api-token: This parameter is optional. If you are setting the token via the environment variable AIRFLOW_CLI_TOKEN, you can skip using this parameter.

–username: This parameter is optional. If you are not using --api-token or the environment variable AIRFLOW_CLI_TOKEN, you must provide a username to authentication along with --password.

–password: This parameter is optional. If you provide a username via --username this is the required password to authenticate.

–env: This parameter is optional. The name of the environment to create or update. The default value is production. This parameter is useful when you want to manage multiple Airflow environments.

More Usage and Help Pictures¶

For more information use

airflowctl auth login --help

You are ready to use airflowctl now. Please, also see Command Line Interface and Environment Variables Reference for the list of available commands and options.

You can use the command airflowctl --help to see the list of available commands.

All Available Group Command References¶

Below are the command reference diagrams for all available commands in airflowctl. These visual references show the full command syntax, options, and parameters for each command.