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

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: 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: 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: Or use environment variables directly (no config file needed): 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 variables List variables af config variable <key Get specific variable af config pools List pools af config pool <name Get pool details af config plugins List plugins af config providers List providers af config assets List assets/datasets af api <endpoint Direct REST API access af api ls List available API endpoints af api ls filter X List endpoints matching pattern af registry providers List providers in the Airflow Registry af registry modules <provider List operators/hooks/sensors/transfers in a provider af registry parameters <provider Constructor signatures (name, type, default, required) for a provider's classes af registry connections <provider Connection types a provider exposes User Intent Patterns Getting Started "How do I run Airflow locally?" / "Set up Airflow" use the managing astro local env skill (uses Astro CLI) "Create a new Airflow project" / "Initialize project" use the setting up astro project skill (uses Astro CLI) "How do I install Airflow?" / "Get started with Airflow" use the setting up astro project skill DAG Operations "What DAGs exist?" / "List all DAGs" af dags list "Tell me about DAG X" / "What is DAG Y?" af dags explore <dag id "What's the schedule for DAG X?" af dags get <dag id "Show me the code for DAG X" af dags source <dag id "Stop DAG X" / "Pause this workflow" af dags pause <dag id "Resume DAG X" af dags unpause <dag id "Are there any DAG errors?" af dags errors "Create a new DAG" / "Write a pipeline" use the authoring dags skill Run Operations "What runs have executed?" af runs list "Run DAG X" / "Trigger the pipeline" af runs trigger <dag id "Run DAG X and wait" af runs trigger wait <dag id "Why did this run fail?" af runs diagnose <dag id <run id "Delete this run" / "Remove stuck run" af runs delete <dag id <run id "Clear this run" / "Retry this run" / "Re run this" af runs clear <dag id <run id "Test this DAG and fix if it fails" use the testing dags skill Task Operations "What tasks are in DAG X?" af tasks list <dag id "Get task logs" / "Why did task fail?" af tasks logs <dag id <run id <task id "Full root cause analysis" / "Diagnose and fix" use the debugging dags skill Data Operations "Is the data fresh?" / "When was this table last updated?" use the checking freshness skill "Where does this data come from?" use the tracing upstream lineage skill "What depends on this table?" / "What breaks if I change this?" use the tracing downstream lineage skill Deployment Operations "Deploy my DAGs" / "Push to production" use the deploying airflow skill "Set up CI/CD" / "Automate deploys" use the deploying airflow skill "Deploy to Kubernetes" / "Set up Helm" use the deploying airflow skill "astro deploy" / "DAG only deploy" use the deploying airflow skill System Operations "What version of Airflow?" af config version "What connections exist?" af config connections "Are pools full?" af config pools "Is Airflow healthy?" af health API Exploration "What API endpoints are available?" af api ls "Find variable endpoints" af api ls filter variable "Access XCom values" / "Get XCom" af api xcom entries F dag id=X F task id=Y "Get event logs" / "Audit trail" af api event logs F dag id=X "Create connection via API" af api connections X POST body '{...}' "Create variable via API" af api variables X POST F key=name f value=val Registry Discovery "What operators does provider X have?" af registry modules <provider "What are the constructor params for operator Y?" af registry parameters <provider "What providers exist?" / "Is there a provider for Z?" af registry providers "What connection types does provider X expose?" af registry connections <provider "Writing a DAG with a specific operator" use registry to verify current signature before copying examples Common Workflows Validate DAGs Before Deploying If you're using the Astro CLI, you can validate DAGs without a running Airflow instance: Otherwise, validate against a running instance: Discover Operator Signatures Before Writing Code The Airflow Registry at airflow.apache.org/registry is the authoritative source for provider classes and their current constructor signatures. Prefer it over memory or stale documentation when authoring DAGs — the registry reflects the live provider release. Results are cached locally: 1 hour for the latest version, 30 days for pinned versions (which are immutable). Add version X.Y.Z to any modules / parameters / connections call to target a specific release. Investigate a Failed Run Morning Health Check Understand a DAG Check Why DAG Isn't Running Trigger and Monitor Output Format All commands output JSON (except instance commands which use human readable tables): Use jq for filtering: Task Logs Options Direct API Access with af api Use af api for endpoints not covered by high level commands (XCom, event logs, backfills, etc). Field syntax : F key=value auto converts types, f key=value keeps as string. Full reference : See [api reference.md](api reference.md) for all options, common endpoints (XCom, event logs, backfills), and examples. Related Skills Skill Use when... authoring dags Creating or editing DAG files with best practices testing dags Iterative test debug fix retest cycles debugging dags Deep root cause analysis and failure diagnosis checking freshness Checking if data is up to date or stale tracing upstream lineage Finding where data comes from tracing downstream lineage Impact analysis what breaks if something changes deploying airflow Deploying DAGs to production (Astro, Docker Compose, Kubernetes) migrating airflow 2 to 3 Upgrading DAGs from Airflow 2.x to 3.x managing astro local env Starting, stopping, or troubleshooting local Airflow setting up astro project Initializing a new Astro/Airflow project airflow state store Per task checkpointing, watermarks, crash safe operators (Airflow 3.3+) airflow hitl Pausing a DAG for human approval or input (Airflow 3.1+)