Metadata-Version: 2.4
Name: afcli
Version: 0.1.9
Summary: A command-line utility for interacting with Apache Airflow REST API
Project-URL: Homepage, https://github.com/ouachitalabs/af
Project-URL: Documentation, https://github.com/ouachitalabs/af#readme
Project-URL: Repository, https://github.com/ouachitalabs/af
Project-URL: Issues, https://github.com/ouachitalabs/af/issues
Author-email: John McCrary <john@ouachitalabs.com>
License: MIT License
        
        Copyright (c) 2025 John McCrary
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: airflow,cli,data-engineering,rest-api,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: apache-airflow-client>=2.8.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Provides-Extra: test
Requires-Dist: freezegun>=1.2.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.11.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Requires-Dist: responses>=0.23.0; extra == 'test'
Description-Content-Type: text/markdown

# Airflow CLI Wrapper

[![Test](https://github.com/ouachitalabs/af/actions/workflows/test.yml/badge.svg)](https://github.com/ouachitalabs/af/actions/workflows/test.yml)
[![PyPI version](https://badge.fury.io/py/afcli.svg)](https://badge.fury.io/py/afcli)
[![Python versions](https://img.shields.io/pypi/pyversions/afcli.svg)](https://pypi.org/project/afcli/)
[![Coverage](https://img.shields.io/badge/coverage-88%25-brightgreen)](https://github.com/ouachitalabs/af)

A command-line utility for interacting with the Airflow REST API. Compatible with both Airflow 2.9.x (basic auth) and 3.x (JWT auth).

## Installation

```bash
uv tool install afcli
```

Or with `pip`:
```bash
pip install afcli
```

## Configuration

### Environment Variables

You can set authentication credentials using environment variables:

```bash
export AIRFLOW_HOST="airflow.example.com:8080"  # Default: localhost:8080
export AIRFLOW_USER="admin"
export AIRFLOW_PASSWORD="your-password"
```

### Command Line Arguments

Command line arguments override environment variables:

```bash
afcli --host airflow.example.com:8080 --user admin --password secret list
```

## Usage

### Basic Usage

By default, the tool connects to `localhost:8080`:

```bash
# Using environment variables
afcli list

# Using command line arguments
afcli --user admin --password secret status my_dag
```

### Available Commands

#### List DAGs
```bash
afcli list
afcli list --limit 10  # Show only 10 DAGs
afcli list --all       # Include inactive DAGs
```

#### View DAG Status
```bash
afcli status <dag_id>
```
Shows DAG configuration and recent runs with color-coded states.

#### Pause/Unpause DAG
```bash
afcli pause <dag_id>
afcli unpause <dag_id>
```

#### Trigger DAG
```bash
afcli trigger <dag_id>
afcli trigger <dag_id> --config '{"key": "value"}'
```

#### View Tasks and Their Status
```bash
afcli tasks <dag_id>
afcli tasks <dag_id> --run-id <specific_run_id>
```
Shows all tasks with color-coded states:
- 🟢 Green: Success
- 🔴 Red: Failed
- 🟡 Yellow: Running/Retry
- 🔵 Blue: Scheduled
- 🟣 Purple: Skipped

#### View Task Logs
```bash
afcli logs <dag_id> <task_id>
afcli logs <dag_id> <task_id> --run-id <specific_run_id> --try-number 2
```

#### Clear Failed Tasks
```bash
# Clear all failed tasks in the latest run
afcli clear <dag_id>

# Clear a specific task
afcli clear <dag_id> --task-id <task_id>

# Skip confirmation prompt
afcli clear <dag_id> -y
```

## Examples

```bash
# Set credentials via environment
export AIRFLOW_USER=admin
export AIRFLOW_PASSWORD=secret

# List all DAGs
afcli list

# Check status of example_dag
afcli status example_dag

# Trigger example_dag with configuration
afcli trigger example_dag --config '{"date": "2024-01-01"}'

# View all tasks in the latest run
afcli tasks example_dag

# View logs for a specific task
afcli logs example_dag process_data

# Clear all failed tasks
afcli clear example_dag
```

## Authentication

The tool automatically detects and uses the appropriate authentication method:

- **Airflow 3.x**: Uses JWT (JSON Web Token) authentication. The tool obtains a token from `/auth/token` and includes it in API requests.
- **Airflow 2.9.x**: Falls back to basic authentication when JWT endpoint is not available.

Authentication happens transparently - simply provide your credentials and the tool will use the appropriate method.

## Development

### Installation for Development

```bash
# Install with test dependencies
uv pip install -e ".[test]"
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=afcli --cov-report=html

# Run specific test categories
pytest -m unit         # Unit tests only
pytest -m integration  # Integration tests only

# Use Makefile commands
make test              # All tests
make test-cov          # With coverage report
make test-unit         # Unit tests only
```
