/airflow

name: airflow
description: Queries, manages, and troubleshoots Apache Airflow using the `af` CLI. Use when working with anything related to Airflow - a DAG, a DAG run, a task log, an import or parse error, a broken DAG, or any Airflow operation. Covers listing and triggering DAGs, retrying runs, reading task logs, diagnosing failures, debugging import and parse errors, checking connections, variables and pools, exploring the REST API, and monitoring health (for example "trigger a pipeline", "retry a run", "list connections", "check Airflow health", "why did my DAG fail"). This is the entrypoint that routes to sibling skills for authoring, testing, deploying, and migrating Airflow 2 to 3. Not for warehouse/SQL analytics on Airflow metadata tables (use analyzing-data); for deep root-cause reports use debugging-dags or airflow-investigation.

Airflow Operations

Use `af` commands to query, manage, and troubleshoot Airflow workflows.

Astro CLI

The [Astro CLI](https://www.astronomer.io/docs/astro/cli/overview) is the recommended way to run Airflow locally and deploy to production. It provides a containerized Airflow environment that works out of the box:

# Initialize a new project
astro dev init

# Start local Airflow (webserver at http://localhost:8080)
astro dev start

# Parse DAGs to catch errors quickly (no need to start Airflow)
astro dev parse

# Run pytest against your DAGs
astro dev pytest

# Deploy to production
astro deploy            # Full deploy (image + DAGs)
astro deploy --dags     # DAG-only deploy (fast, no image build)

For more details:

• **New project?** See the **setting-up-astro-project** skill
• **Local environment?** See the **managing-astro-local-env** skill
• **Deploying?** See the **deploying-airflow** skill

---

Running the CLI

These commands assume `af` is on PATH. Run via `astro otto` to get it automatically, or install standalone with `uv tool install astro-airflow-mcp`.

Instance Configuration

Manage multiple Airflow instances with persistent configuration:

# Add a new instance
af instance add prod --url https://airflow.example.com --token "$API_TOKEN"
af instance add staging --url https://staging.example.com --username admin --password admin

# List and switch instances
af instance list      # Shows all instances in a table
af instance use prod  # Switch to prod instance
af instance current   # Show current instance
af instance delete old-instance

# Auto-discover instances (use --dry-run to preview first)
af instance discover --dry-run        # Preview all discoverable instances
af instance discover                  # Discover from all backends (astro, local)
af instance discover astro            # Discover Astro deployments only
af instance discover astro --all-workspaces  # Include all accessible workspaces
af instance discover local            # Scan common local Airflow ports
af instance discover local --scan     # Deep scan all ports 1024-65535

# IMPORTANT: Always run with --dry-run first and ask for user consent before
# running discover without it. The non-dry-run mode creates API tokens in
# Astro Cloud, which is a sensitive action that requires explicit approval.

# Show where an instance came from (file path + scope)
af instance show prod

# Override instance for a single command via env vars
AIRFLOW_API_URL=https://staging.example.com AIRFLOW_AUTH_TOKEN=$STG af dags list

# Or switch persistently
af instance use staging

Config layout (mirrors `git config` system/global/local):

| Scope | File | Committed? | |---|---|---| | Global | `~/.astro/config.yaml` | n/a (per-user) | | Project shared | `<root>/.astro/config.yaml` | yes | | Project local | `<root>/.astro/config.local.yaml` | no (gitignored) |

`<root>` is found by walking up from cwd looking for `.astro/`. Default write routing inside a project: `add`/`discover` → project-shared, `use` → project-local. Override with `--global` / `--project` / `--local`. Set `AF_CONFIG=<path>` to bypass layering and use a single file.

Migrate from the legacy `~/.af/config.yaml` with `af migrate` (idempotent; renames the old file to `.bak`).

Tokens in config can reference environment variables using `${VAR}` syntax:

instances:
- name: prod
  url: https://airflow.example.com
  auth:
    token: ${AIRFLOW_API_TOKEN}

Or use environment variables directly (no config file needed):

export AIRFLOW_API_URL=http://localhost:8080
export AIRFLOW_AUTH_TOKEN=your-token-here
# Or username/password:
export AIRFLOW_USERNAME=admin
export AIRFLOW_PASSWORD=admin

Or CLI flags: `af --airflow-url http://localhost:8080 --token "$TOKEN" <command>`

Quick Reference

| Command | Description | |---------|-------------| | `af health` | System health check | | `af dags list` | List all DAGs | | `af dags get <dag_id>` | Get DAG details | | `af dags explore <dag_id>` | Full DAG investigation | | `af dags source <dag_id>` | Get DAG source code | | `af dags pause <dag_id>` | Pause DAG scheduling | | `af dags unpause <dag_id>` | Resume DAG scheduling | | `af dags errors` | List import errors | | `af dags warnings` | List DAG warnings | | `af dags stats` | DAG run statistics | | `af runs list` | List DAG runs | | `af runs get <dag_id> <run_id>` | Get run details | | `af runs trigger <dag_id>` | Trigger a DAG run | | `af runs trigger-wait <dag_id>` | Trigger and wait for completion | | `af runs delete <dag_id> <run_id>` | Permanently delete a DAG run | | `af runs clear <dag_id> <run_id>` | Clear a run for re-execution | | `af runs diagnose <dag_id> <run_id>` | Diagnose failed run | | `af tasks list <dag_id>` | List tasks in DAG | | `af tasks get <dag_id> <task_id>` | Get task definition | | `af tasks instance <dag_id> <run_id> <task_id>` | Get task instance | | `af tasks logs <dag_id> <run_id> <task_id>` | Get task logs | | `af config version` | Airflow version | | `af config show` | Full configuration | | `af config connections` | List connections | | `af config va