Apache Airflow Admin CLI

Apache Airflow is an open-source workflow orchestrator used by data teams to schedule and monitor data pipelines. A pipeline is usually modeled as a DAG: a set of tasks with dependencies, retries, schedules, and run history. Data engineers use Airflow to keep warehouse loads, API extracts, dbt jobs, reports, and machine-learning workflows running on time.

This CLI gives engineers and agents a read-first way to inspect an Airflow environment from the terminal. It can list DAGs, inspect recent DAG runs, check task instance failures, review pools, verify Airflow health, and sync useful metadata into a local SQLite store for search and analysis. It is not a replacement for the Airflow UI; it is a compact operations surface for answering questions such as "what failed overnight?", "which tasks are still retrying?", and "is the scheduler healthy?" without opening the browser.

Printed by @sdhilip200 (Dhilip Subramanian).

Quick Start

1. Install

See Install above.

2. Point the CLI at Airflow

The default base URL is http://localhost:8080, which matches a common local Airflow setup. For another environment, set AIRFLOW_ADMIN_BASE_URL:

export AIRFLOW_ADMIN_BASE_URL="https://airflow.example.com"

3. Get and store an Airflow token

For a local Airflow instance using the default demo credentials, request a JWT token from Airflow:

airflow-admin-pp-cli apache-airflow-admin-auth \
  --username airflow \
  --password airflow \
  --json

Copy the access_token value from the response and store it:

airflow-admin-pp-cli auth set-token <access_token>

You can also provide the token only for the current shell:

export AIRFLOW_ADMIN_BEARER_AUTH="<access_token>"

Do not commit tokens or Airflow passwords. Keep them in your shell environment, local config file, or your MCP client's secret prompt.

4. Verify setup

airflow-admin-pp-cli doctor

This checks your configuration and credentials.

5. Try the common operations commands

airflow-admin-pp-cli apache-airflow-admin-version
airflow-admin-pp-cli monitor
airflow-admin-pp-cli dags list

Usage

Run airflow-admin-pp-cli --help for the full command reference and flag list.

Commands

apache-airflow-admin-auth

Manage apache airflow admin auth

• airflow-admin-pp-cli apache-airflow-admin-auth - Authenticate with an Airflow username and password and return a JWT access token.

apache-airflow-admin-version

Manage apache airflow admin version

• airflow-admin-pp-cli apache-airflow-admin-version - Get Airflow version

connections

Airflow connection metadata.

• airflow-admin-pp-cli connections - List connections

dags

DAG inventory and metadata.

• airflow-admin-pp-cli dags get - Get DAG
• airflow-admin-pp-cli dags list - List DAGs
• airflow-admin-pp-cli dags dag-runs list - List DAG runs for a DAG
• airflow-admin-pp-cli dags dag-runs get - Get a single DAG run
• airflow-admin-pp-cli dags dag-runs list-task-instances - List task instances for a DAG run
• airflow-admin-pp-cli dags dag-runs get-task-instance - Get one task instance
• airflow-admin-pp-cli dags tasks list - List tasks in a DAG
• airflow-admin-pp-cli dags details - Get detailed DAG metadata

monitor

Manage monitor

• airflow-admin-pp-cli monitor - Get health

pools

Airflow pool capacity and occupancy.

• airflow-admin-pp-cli pools get - Get pool
• airflow-admin-pp-cli pools list - List pools

variables

Airflow variable metadata.

• airflow-admin-pp-cli variables - List variables

Data Engineering Workflows

Check whether Airflow itself is healthy:

airflow-admin-pp-cli monitor --json
airflow-admin-pp-cli apache-airflow-admin-version --json

List active DAGs and keep the output small for a script or agent:

airflow-admin-pp-cli dags list --json --select dag_id,is_active,is_paused,last_parsed_time

Inspect failed DAG runs for a pipeline:

airflow-admin-pp-cli dags dag-runs list daily_warehouse_refresh \
  --state failed \
  --start-date-gte 2026-06-01T00:00:00Z \
  --json \
  --select dag_id,dag_run_id,state,start_date,end_date

Inspect failed task instances inside a DAG run:

airflow-admin-pp-cli dags dag-runs list-task-instances \
  daily_warehouse_refresh \
  scheduled__2026-06-14T00:00:00+00:00 \
  --state failed \
  --json \
  --select task_id,state,try_number,start_date,end_date

Sync metadata locally, then search it without repeatedly paging the API:

airflow-admin-pp-cli sync --resources dags,pools --json
airflow-admin-pp-cli search "failed" --data-source local --json --limit 20
airflow-admin-pp-cli analytics count --type dag-runs

Output Formats

# Human-readable table (default in terminal, JSON when piped)
airflow-admin-pp-cli apache-airflow-admin-version

# JSON for scripting and agents
airflow-admin-pp-cli apache-airflow-admin-version --json

# Filter to specific fields
airflow-admin-pp-cli apache-airflow-admin-version --json --select id,name,status

# Dry run — show the request without sending
airflow-admin-pp-cli apache-airflow-admin-version --dry-run

# Agent mode — JSON + compact + no prompts in one flag
airflow-admin-pp-cli apache-airflow-admin-version --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

airflow-admin-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/airflow-admin-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
AIRFLOW_ADMIN_BASE_URL	connection	No	Airflow webserver/API base URL. Defaults to http://localhost:8080.
AIRFLOW_ADMIN_BEARER_AUTH	credential	Yes	Airflow JWT access token, without the Bearer prefix.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, airflow-admin-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run airflow-admin-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $AIRFLOW_ADMIN_BEARER_AUTH Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press