Apache Airflow with Astronomer CLI

Use astro for local Apache Airflow development, DAG authoring, task testing, and debugging. python-stack owns Python package conventions and docker manages container runtimes.

Docker mode (the default) needs an existing Docker-compatible engine; run dot doctor --headroom before the first image pull or build. --standalone runs Airflow on the host without Docker. Workstation tools disable anonymous telemetry (ASTRO_TELEMETRY_DISABLED=1). Inspect the project's Airflow version before choosing component flags for astro dev logs and astro dev bash (--api-server and --dag-processor for Airflow 3; --webserver for Airflow 2). astro dev bash opens an interactive shell, so agents run Airflow commands through astro dev run instead.

Workflow

1. Start local environment: --no-browser keeps the UI from opening.

   astro dev start --no-browser

2. Validate DAG syntax and integrity: parse DAG files to catch import and configuration errors without waiting for the scheduler.

   astro dev parse

3. Test tasks and runs: execute unit tests or run individual tasks directly inside the local environment.

   astro dev pytest
   astro dev run tasks test <dag_id> <task_id>

4. Inspect service and task logs: select the relevant component and keep --follow opt-in.

   astro dev logs --scheduler
   astro dev logs --api-server

5. Stop or rebuild environment: stop containers when done or rebuild when changing dependencies in requirements.txt.

   astro dev stop
   # After changing requirements.txt or Dockerfile:
   astro dev restart

Gotchas

• Author Airflow 3 DAGs with airflow.sdk: import dag, task, and DAG from airflow.sdk; ruff check --select AIR3 flags removed and deprecated Airflow 2 imports before astro dev upgrade-test.
• Proxy URLs replace fixed ports: by default a shared reverse proxy serves each project at http://<project>.localhost:6563 on random backend ports; astro dev proxy status lists each project's URL and Postgres port. --no-proxy restores fixed ports (8080 for the API server or webserver, 5432 for Postgres), which can collide with local services.
• Task tests record no state: astro dev run tasks test runs a single task without recording state in the Airflow database; upstream task dependencies must be handled or mocked.
• Run upgrade-test before upgrading: before moving to a newer Airflow or Astro Runtime (including Airflow 2 to 3), run astro dev upgrade-test (optionally --airflow-version <version>); it reports dependency changes, DAG import errors, and deprecation lint in an upgrade-test-<current>--<new>/ folder inside the project and temporarily appends pytest-html to requirements.txt; --fix rewrites project files with ruff fixes, including unsafe ones.

Official Skills

Upstream: Astronomer Agent Skills at astronomer/agents (including Airflow 2-to-3 migration). Its airflow skill drives the af CLI and shares this skill's name: preview it, never install it under that name, and install only selected non-colliding skills under the shared vendor-skill policy.

Documentation

• Astronomer CLI Documentation · Apache Airflow Documentation
• Releases: Astronomer CLI Releases
• Companion skills: python-stack (Python coding), docker (containers), duckdb (inspect task outputs).