Supports 30+ commands across DAG inspection, run management, task logging, configuration queries, and direct REST API access
Manage multiple Airflow instances with persistent configuration; auto-discover local and Astro deployments
Trigger DAG runs synchronously (wait for completion) or asynchronously, diagnose failures, clear runs for retry, and access task logs with retry/map-index filtering
Fetches airflow from astronomer/agents and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/airflow
Restart Cursor to activate airflow. Access via /airflow in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
Use af commands to query, manage, and troubleshoot Airflow workflows.
Astro CLI
The Astro CLI 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 projectastro 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 DAGsastro dev pytest
# Deploy to productionastro 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
Run all af commands using uvx (no installation required):
uvx --from astro-airflow-mcp af <command>
Throughout this document, af is shorthand for uvx --from astro-airflow-mcp af.
Instance Configuration
Manage multiple Airflow instances with persistent configuration:
# Add a new instanceaf 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 instancesaf instance list # Shows all instances in a tableaf instance use prod # Switch to prod instanceaf instance current # Show current instanceaf instance delete old-instance
# Auto-discover instances (use --dry-run to preview first)af instance discover --dry-run # Preview all discoverable instancesaf instance discover # Discover from all backends (astro, local)af instance discover astro # Discover Astro deployments onlyaf instance discover astro --all-workspaces # Include all accessible workspacesaf instance discover local# Scan common local Airflow portsaf 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.# Override instance for a single commandaf --instance staging dags list
Config file: ~/.af/config.yaml (override with --config or AF_CONFIG env var)
Tokens in config can reference environment variables using ${VAR} syntax:
Or use environment variables directly (no config file needed):
exportAIRFLOW_API_URL=http://localhost:8080
exportAIRFLOW_AUTH_TOKEN=your-token-here
# Or username/password:exportAIRFLOW_USERNAME=admin
exportAIRFLOW_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 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
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
Common Workflows
Validate DAGs Before Deploying
If you're using the Astro CLI, you can validate DAGs without a running Airflow instance:
# Parse DAGs to catch import errors and syntax issuesastro dev parse
# Run unit testsastro dev pytest
Otherwise, validate against a running instance:
af dags errors # Check for parse/import errorsaf dags warnings # Check for deprecation warnings
Investigate a Failed Run
# 1. List recent runs to find failureaf runs list --dag-id my_dag
# 2. Diagnose the specific runaf runs diagnose my_dag manual__2024-01-15T10:00:00+00:00
# 3. Get logs for failed task (from diagnose output)af tasks logs my_dag manual__2024-01-15T10:00:00+00:00 extract_data
# 4. After fixing, clear the run to retry all tasksaf runs clear my_dag manual__2024-01-15T10:00:00+00:00
Morning Health Check
# 1. Overall system healthaf health
# 2. Check for broken DAGsaf dags errors
# 3. Check pool utilizationaf config pools
# Check if pausedaf dags get my_dag
# Check for import errorsaf dags errors
# Check recent runsaf runs list --dag-id my_dag
Trigger and Monitor
# Option 1: Trigger and wait (blocking)af runs trigger-wait my_dag --timeout1800# Option 2: Trigger and check lateraf runs trigger my_dag
af runs get my_dag <run_id>
Output Format
All commands output JSON (except instance commands which use human-readable tables):
af dags list
# {# "total_dags": 5,# "returned_count": 5,# "dags": [...]# }
Use jq for filtering:
# Find failed runsaf runs list | jq '.dag_runs[] | select(.state == "failed")'# Get DAG IDs onlyaf dags list | jq '.dags[].dag_id'# Find paused DAGsaf dags list | jq '[.dags[] | select(.is_paused == true)]'
Task Logs Options
# Get logs for specific retry attemptaf tasks logs my_dag run_id task_id --try2# Get logs for mapped task indexaf tasks logs my_dag run_id task_id --map-index 5
Direct API Access with af api
Use af api for endpoints not covered by high-level commands (XCom, event-logs, backfills, etc).
# Discover available endpointsaf api lsaf api ls--filter variable
# Basic usageaf api dags
af api dags -Flimit=10-Fonly_active=true
af api variables -X POST -Fkey=my_var -fvalue="my value"af api variables/old_var -X DELETE
Field syntax: -F key=value auto-converts types, -f key=value keeps as string.
Full reference: See 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
Implementation Guide
Prerequisites
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
