# Airflow CLI: Cheatsheet
***
### Airflow 3.x commands
***
[CLI commands and environment variables reference](https://airflow.apache.org/docs/apache-airflow/stable/cli-and-env-variables-ref.html)
[Configuration reference](https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html) (for when you run `airflow config list`).
***
**The Airflow Command Line Interface (CLI)** is an essential tool for developers, offering capabilities that go beyond what is available in the web UI. It is often faster for debugging, environment management, and manual task intervention.
Here's a cheatsheet Airflow 3.1.3 outputs after running `airflow cheat-sheet` command:
```bash
Miscellaneous commands
airflow api-server | Start an Airflow API server instance
airflow cheat-sheet | Display cheat sheet
airflow dag-processor | Start a dag processor instance
airflow info | Show information about current Airflow
| and environment
airflow kerberos | Start a kerberos ticket renewer
airflow plugins | Dump information about loaded plugins
airflow rotate-fernet-key | Rotate encrypted connection credentials
| and variables
airflow scheduler | Start a scheduler instance
airflow triggerer | Start a triggerer instance
airflow version | Show the version
---
Manage assets
airflow assets details | Show asset details
airflow assets list | List assets
airflow assets materialize | Materialize an asset
---
Manage backfills
airflow backfill create | Create a backfill for a dag.
---
View configuration
airflow config get-value | Print the value of the configuration
airflow config lint | lint options for the configuration
| changes while migrating from Airflow 2.x
| to Airflow 3.0
airflow config list | List options for the configuration
airflow config update | update options for the configuration
| changes while migrating from Airflow 2.x
| to Airflow 3.0
---
Manage connections
airflow connections add | Add a connection
airflow connections create-default-connections | Creates all the default connections from
| all the providers
airflow connections delete | Delete a connection
airflow connections export | Export all connections
airflow connections get | Get a connection
airflow connections import | Import connections from a file
airflow connections list | List connections
airflow connections test | Test a connection
---
Manage DAGs
airflow dags delete | Delete all DB records related to the
| specified DAG
airflow dags details | Get DAG details given a DAG id
airflow dags list | List all the DAGs
airflow dags list-import-errors | List all the DAGs that have import errors
airflow dags list-jobs | List the jobs
airflow dags list-runs | List DAG runs given a DAG id
airflow dags next-execution | Get the next logical datetimes of a DAG
airflow dags pause | Pause DAG(s)
airflow dags report | Show DagBag loading report
airflow dags reserialize | Reserialize DAGs by parsing the DagBag
| files
airflow dags show | Displays DAG\'s tasks with their
| dependencies
airflow dags show-dependencies | Displays DAGs with their dependencies
airflow dags state | Get the status of a dag run
airflow dags test | Execute one single DagRun
airflow dags trigger | Trigger a new DAG run. If DAG is paused
| then dagrun state will remain queued, and
| the task won\'t run.
airflow dags unpause | Resume paused DAG(s)
---
Database operations
airflow db check | Check if the database can be reached
airflow db check-migrations | Check if migration have finished
airflow db clean | Purge old records in metastore tables
airflow db downgrade | Downgrade the schema of the metadata
| database.
airflow db drop-archived | Drop archived tables created through the
| db clean command
airflow db export-archived | Export archived data from the archive
| tables
airflow db migrate | Migrates the metadata database to the
| latest version
airflow db reset | Burn down and rebuild the metadata
| database
airflow db shell | Runs a shell to access the database
---
Manage externally connected database managers
airflow db-manager downgrade | Downgrade the schema of the external
| metadata database.
airflow db-manager migrate | Migrates the specified external database
| to the latest version
airflow db-manager reset | Burn down and rebuild the specified
| external database
---
Manage jobs
airflow jobs check | Checks if job(s) are still alive
---
Manage pools
airflow pools delete | Delete pool
airflow pools export | Export all pools
airflow pools get | Get pool size
airflow pools import | Import pools
airflow pools list | List pools
airflow pools set | Configure pool
---
Display providers
airflow providers auth-managers | Get information about auth managers
| provided
airflow providers behaviours | Get information about registered
| connection types with custom behaviours
airflow providers configs | Get information about provider
| configuration
airflow providers executors | Get information about executors provided
airflow providers get | Get detailed information about a provider
airflow providers hooks | List registered provider hooks
airflow providers lazy-loaded | Checks that provider configuration is
| lazy loaded
airflow providers links | List extra links registered by the
| providers
airflow providers list | List installed providers
airflow providers logging | Get information about task logging
| handlers provided
airflow providers notifications | Get information about notifications
| provided
airflow providers queues | Get information about queues provided
airflow providers secrets | Get information about secrets backends
| provided
airflow providers triggers | List registered provider triggers
airflow providers widgets | Get information about registered
| connection form widgets
---
Manage tasks
airflow tasks clear | Clear a set of task instance, as if they
| never ran
airflow tasks failed-deps | Returns the unmet dependencies for a task
| instance
airflow tasks list | List the tasks within a DAG
airflow tasks render | Render a task instance\'s template(s)
airflow tasks state | Get the status of a task instance
airflow tasks states-for-dag-run | Get the status of all task instances in a
| dag run
airflow tasks test | Test a task instance
---
Manage variables
airflow variables delete | Delete variable
airflow variables export | Export all variables
airflow variables get | Get variable
airflow variables import | Import variables
airflow variables list | List variables
airflow variables set | Set variable
```
Usage suggestions for some of the above described commands
**Getting Started and Environment Discovery**
When you first set up Airflow, the CLI helps you initialize the metadata database and verify that your environment is correctly configured.
* `airflow db init` / `airflow db upgrade`: Used to set up the backend database where Airflow stores task statuses and DAG metadata.
* `airflow info`: Provides a comprehensive summary of your environment, including version numbers, executor type, database info, and paths. This is the first command you should run if you need to troubleshoot installation issues.
* `airflow config list`: Displays all the configuration settings currently active in your environment, helping you understand how Airflow is behaving under the hood.
***
**Debugging and Testing Tasks**
The CLI is the "surgical tool" for testing individual tasks without needing to run an entire DAG or wait for a schedule.
* `airflow dags list`: Lists all DAGs that the scheduler has successfully parsed. If your DAG isn't here, you have a syntax error.
* `airflow tasks list `: Shows the hierarchy of tasks within a specific DAG.
* `airflow tasks test `: Crucial for development. This runs a single task instance locally without recording the result in the database. It allows you to see the logs and errors immediately in your terminal.
* `airflow dags report`: Summarizes which DAG files are taking a long time to parse, helping you optimize slow-loading environments.
***
**Exporting and Importing Settings**
Managing "Variables" and "Connections" is often easier through the CLI, especially when moving between development and production environments.
* `airflow variables export `: Dumps all your UI-defined variables into a JSON file.
* `airflow variables import `: Uploads variables from a file into a new environment.
* `airflow connections export `: Similar to variables, this helps you back up your database connection strings and credentials safely.
***
**The Backfill Command**
One of the most powerful CLI features is the ability to run historical data. While the UI can "Clear" runs to re-run them, the CLI's `backfill` command is more robust for large ranges of time.
* `airflow dags backfill -s -e `: This command forces the DAG to run for every interval between the start and end dates.
* Note: Backfill behaves differently than a standard "Clear"; it doesn't necessarily respect the same dependency limits as the scheduler, so use it carefully in production.
***
**CLI vs. UI: Why use the CLI?**
The CLI provides specific "power user" options that the UI lacks:
| **Feature** | **Airflow UI** | **Airflow CLI** |
| ----------------- | ---------------------------- | ----------------------------------------- |
| **Task Testing** | Must run whole DAG / Trigger | `airflow tasks test` (Instant & Local) |
| **Bulk Backfill** | Manual clearing of runs | `airflow dags backfill` (Automated range) |
| **System Info** | Limited | `airflow info` (Full system diagnostic) |
| **DB Management** | None | `airflow db shell` (Direct SQL access) |
***
**Summary of Key Commands**
| **Command** | **Primary Use Case** |
| -------------------------- | ------------------------------------------------------ |
| `airflow tasks test` | Verify Python logic/Jinja templates for a single task. |
| `airflow dags backfill` | Run a DAG for a historical time range. |
| `airflow info` | Debug environment and configuration issues. |
| `airflow variables export` | Migrate settings between environments. |
***
### Where to use these commands
These commands are the "Universal Language" of Airflow. Whether you are running Airflow on your laptop, in Docker, or on a massive production cluster in the cloud, the `airflow` CLI remains your primary tool for talking to the system.
However, how you run them changes depending on your deployment.
***
#### Where the commands live
The relevance of these commands depends on which "part" of Airflow you are talking to.
* **Local/Virtual Env:** You just type `airflow dags list`.
* **Docker Compose:** You have to tell Docker which container should run the command:
`docker compose run airflow-worker airflow dags list`
* **Kubernetes (Helm):** You usually exec into a pod:
`kubectl exec -it -- airflow dags list`
* **Managed Cloud (AWS MWAA/Google Cloud Composer):** They often provide a wrapper in their own CLI (e.g., `gcloud composer environments run...`).
#### High-Value Commands for local Docker setup
Here are the commands from that list that you will actually use 90% of the time in a testing environment:
| **Command** | **Why it's a lifesaver** |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `airflow dags test` | Critical. It runs a DAG locally without needing the scheduler. Great for checking if your logic works before "deploying" it to the UI. |
| `airflow tasks render` | Use this to see if your \`{{ logical\_date |
| `airflow config list` | Shows you every setting currently active. If you're wondering "Where is my DAG folder pointing?", this tells you. |
| `airflow db migrate` | Essential when upgrading Airflow. It updates your database schema to match the new version. |
| `airflow connections export` | Very useful for backing up your database passwords and API keys to a file. |
***
#### What changes in Airflow 3.x?
You'll notice a few new entries in that cheat-sheet that are specific to the **3.x architecture:**
* `airflow api-server`: In Airflow 3, the API is more **decoupled**. This command starts the specialized server that handles REST requests.
* `airflow dag-processor`: In older versions, the Scheduler parsed DAGs. In Airflow 3 (and high-scale Airflow 2 setups), this is its own standalone process to improve performance.
* `airflow assets ...`: This replaces the old "Datasets" terminology. It’s used for data-aware scheduling (e.g., "Run DAG B as soon as a new file/asset is created by DAG A").
#### A Note on `airflow standalone`
**Warning: Do not use this inside your Docker environment**. `standalone` is meant for a quick "I want to try Airflow in 30 seconds on my bare laptop" experience. If you have a Docker Compose setup with separate Postgres and Redis containers, using `standalone` would create a "mini-Airflow" inside one of your containers, causing massive confusion.
***
### How High-Value Commands Translate to Production
| **Command** | **Production Use Case** |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `airflow tasks clear` | **The "Fix-it" Tool.** If a pipeline failed halfway through due to a temporary database outage, you use this to clear the status of the failed tasks so the scheduler picks them up and retries them. |
| `airflow tasks render` | **The "Debugger."** When a production task fails with "File not found," you run this to see exactly what file path the production server was looking for. |
| `airflow dags backfill` | **The "Time Machine."** If you find a bug in your logic that existed for the last month, you use this to re-run the last 30 days of data with the new, corrected code. |
| `airflow connections import` | **The "Provisioner."** In production, you don't want to type passwords into a UI. You use this command in a CI/CD script to automatically load your production credentials. |
| `airflow db migrate` | **The "Upgrader."** Every time you upgrade your production Airflow version, this command is run (usually automatically) to ensure your database stays healthy. |
#### The Production "Safety" Difference
While the commands are the same, the environment adds rules:
* **Read-Only Access:** In many companies, your production Airflow might be locked down. You might only be able to run "Read" commands (like `dags list` or `tasks state`) but not "Write" commands (like `db reset`—which you should never run in production).
* **The "Worker" Context:** In production, if you run `airflow tasks test`, it runs the code *on the machine you are typed into*. In a cluster, that machine might not have access to the same folders or databases as the official Airflow Workers.
* **Audit Logs:** Almost every CLI command you run in production is logged. If you manually trigger a DAG or clear a task via CLI, your team leads will see who did it and when.
#### One Command to be Careful With
In your local Docker, you might use `airflow db reset` to wipe everything and start over.
> **Warning:** Never use `db reset` or `db drop-archived` in production unless you intend to delete every single piece of history, connection, and user account Airflow has ever stored.
***