Airflow CLI: Cheatsheet

---

Airflow 3.x commands

---

CLI commands and environment variables reference

Configuration reference (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:

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 <dag_id>: Shows the hierarchy of tasks within a specific DAG.

• airflow tasks test <dag_id> <task_id> <logical_date>: 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 <file.json>: Dumps all your UI-defined variables into a JSON file.

• airflow variables import <file.json>: Uploads variables from a file into a new environment.

• airflow connections export <file.json>: 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 <start_date> -e <end_date> <dag_id>: 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 <pod-name> -- 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.

---