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 DAGairflow-admin-pp-cli dags list - List DAGsairflow-admin-pp-cli dags dag-runs list - List DAG runs for a DAGairflow-admin-pp-cli dags dag-runs get - Get a single DAG runairflow-admin-pp-cli dags dag-runs list-task-instances - List task instances for a DAG runairflow-admin-pp-cli dags dag-runs get-task-instance - Get one task instanceairflow-admin-pp-cli dags tasks list - List tasks in a DAGairflow-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 poolairflow-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