Metadata-Version: 2.4
Name: adop-cli
Version: 0.1.9
Summary: CLI tool to trigger Azure DevOps pipelines
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Azure DevOps Pipeline CLI

A command-line tool to trigger and manage Azure DevOps pipelines with ease.

## Features

- **Trigger Pipelines** - Start builds with a single command
- **Watch Progress** - Real-time build status with progress bar
- **Build Management** - View status, logs, cancel, compare builds
- **Favorites** - Save and reuse common build configurations
- **Shell Completion** - Tab-complete pipeline aliases and branches
- **Fuzzy Matching** - Suggests corrections for typos

## Installation

### Homebrew (macOS/Linux)

```bash
brew tap SAGARSURI/tap
brew install adop-cli
```

### pip

```bash
pip install adop-cli
```

### From Source

```bash
git clone https://github.com/SAGARSURI/adop.git
cd adop
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Setup

### 1. Configure Azure DevOps Connection

```bash
ado-pipeline config init
```

You'll be prompted to enter:
- **Organization** - Your Azure DevOps organization name
- **Project** - Your Azure DevOps project name
- **PAT** - Personal Access Token

**Required PAT Permissions:**
- Build: Read & execute
- Code: Read
- User Profile: Read (optional, for `--mine` flag)

### 2. Add Pipelines

After configuring, add pipelines you want to manage:

```bash
# Import pipelines from Azure DevOps (interactive)
ado-pipeline pipeline import

# Or add manually
ado-pipeline pipeline add my-build "My Pipeline Name" --description "Build description"

# Add with parameters
ado-pipeline pipeline add android-build "Android_Build" \
  --param "outputFormat:choice:apk:apk,aab" \
  --param "deploy:boolean:false" \
  --param "releaseNotes:string:"
```

### 3. Enable Shell Completion (Optional)

```bash
# Bash - add to ~/.bashrc
eval "$(_ADO_PIPELINE_COMPLETE=bash_source ado-pipeline)"

# Zsh - add to ~/.zshrc
eval "$(_ADO_PIPELINE_COMPLETE=zsh_source ado-pipeline)"
```

This enables tab-completion for pipeline aliases and git branches.

## Quick Start

```bash
# List available pipelines
ado-pipeline list

# See what would be triggered (dry-run)
ado-pipeline plan my-build

# Trigger a build
ado-pipeline apply my-build

# Trigger and watch progress
ado-pipeline apply my-build -y -w

# Check build status
ado-pipeline status

# Open build in browser
ado-pipeline open <BUILD_ID>
```

## Commands

### Trigger Pipelines

#### Plan Mode (Dry Run)

Preview what will be triggered without making API calls:

```bash
ado-pipeline plan my-build
ado-pipeline plan my-build --branch feature/my-feature
ado-pipeline plan my-build -p deploy=true -p outputFormat=aab
```

#### Apply Mode (Trigger)

Actually trigger the pipeline:

```bash
# Basic trigger (prompts for confirmation)
ado-pipeline apply my-build

# Skip confirmation
ado-pipeline apply my-build -y

# Skip confirmation and watch progress
ado-pipeline apply my-build -y -w

# With parameters
ado-pipeline apply my-build -p deploy=true -p outputFormat=aab
ado-pipeline apply my-build --branch main -p environment=prod
```

### Build Management

#### View Build Status

```bash
# Show recent builds
ado-pipeline status

# Show more builds
ado-pipeline status -n 20

# Filter by pipeline
ado-pipeline status -p my-build

# Show only your builds
ado-pipeline status --mine
```

#### View Build Logs

```bash
# Show logs for a build
ado-pipeline logs <BUILD_ID>

# Stream logs in real-time
ado-pipeline logs <BUILD_ID> -f
```

#### Cancel a Build

```bash
ado-pipeline cancel <BUILD_ID>
ado-pipeline cancel <BUILD_ID> -y    # Skip confirmation
```

#### Open Build in Browser

```bash
ado-pipeline open <BUILD_ID>
```

#### Compare Two Builds

```bash
ado-pipeline diff <BUILD_ID_1> <BUILD_ID_2>
```

Shows side-by-side comparison of pipeline, branch, result, duration, and parameters.

### Pipeline Management

#### List Configured Pipelines

```bash
ado-pipeline pipeline list
```

#### Add a Pipeline

```bash
# Basic
ado-pipeline pipeline add <alias> "<Azure DevOps Pipeline Name>"

# With description
ado-pipeline pipeline add my-build "My_Build_Pipeline" --description "Main build"

# With parameters
ado-pipeline pipeline add my-build "My_Build_Pipeline" \
  --param "outputFormat:choice:apk:apk,aab" \
  --param "deploy:boolean:false" \
  --param "environment:string:dev"
```

Parameter format: `name:type:default[:choices]`
- Types: `string`, `boolean`, `choice`
- For choice type, add comma-separated options after default

#### Import from Azure DevOps

```bash
# Interactive import from remote
ado-pipeline pipeline import
```

This fetches available pipelines from Azure DevOps and lets you add them interactively.

#### View Pipeline Parameters

```bash
# Show available parameters for a pipeline
ado-pipeline pipeline params my-build

# Or use the Azure DevOps pipeline name
ado-pipeline pipeline params "My_Build_Pipeline"
```

Fetches the pipeline's YAML file and displays available parameters with their types, defaults, and allowed values.

#### Sync Parameters from Azure DevOps

```bash
# Fetch and save parameters locally
ado-pipeline pipeline sync my-build
```

This fetches parameters from Azure DevOps and saves them to your local config, so they appear in `ado-pipeline list`.

#### Remove a Pipeline

```bash
ado-pipeline pipeline remove <alias>
```

### Favorites

Save frequently used build configurations for quick access.

#### Save a Favorite

```bash
# Save with deploy enabled
ado-pipeline fav add quick-build my-build --deploy

# Save with specific branch
ado-pipeline fav add release-build my-prod --branch main --deploy
```

#### List Favorites

```bash
ado-pipeline fav list
```

#### Run a Favorite

```bash
ado-pipeline fav run quick-build
ado-pipeline fav run quick-build -y -w    # Skip confirmation + watch
```

#### Remove a Favorite

```bash
ado-pipeline fav remove quick-build
```

### Configuration

```bash
# Initialize or update configuration
ado-pipeline config init

# Show current configuration
ado-pipeline config show
```

## Parameters

Pass parameters using the generic `-p` or `--param` flag with `name=value` format:

```bash
# Single parameter
ado-pipeline apply my-build -p deploy=true

# Multiple parameters
ado-pipeline apply my-build -p outputFormat=aab -p deploy=true -p releaseNotes="Bug fixes"
```

**Boolean values:** Use `true/yes/1` or `false/no/0`

**Discover parameters:** Use `ado-pipeline pipeline params <alias>` to see available parameters for a pipeline.

### Common Options

| Option | Description |
|--------|-------------|
| `--branch`, `-b` | Branch to build (default: current branch) |
| `--yes`, `-y` | Skip confirmation prompt |
| `--watch`, `-w` | Watch build progress until completion |

## Configuration Files

| File | Purpose |
|------|---------|
| `~/.azure-pipeline-cli/config.json` | PAT and organization settings |
| `~/.azure-pipeline-cli/pipelines.json` | Pipeline definitions |
| `~/.azure-pipeline-cli/favorites.json` | Saved favorite configurations |

All files have `0600` permissions (owner read/write only) since they may contain sensitive data.

## Troubleshooting

### "Pipeline not found"

The CLI suggests similar names if you make a typo:
```
Error: Pipeline 'my-bild' not found. Did you mean: my-build?
```

Run `ado-pipeline pipeline list` to see all available aliases.

### "No pipelines configured"

Add pipelines first:
```bash
ado-pipeline pipeline import   # Import from Azure DevOps
# or
ado-pipeline pipeline add <alias> "<pipeline-name>"
```

### "PAT not configured"

Run `ado-pipeline config init` and enter your credentials.

### "Branch not found"

The branch must exist on the remote. Push it first:
```bash
git push -u origin <branch>
```

### "Could not determine current user"

The `--mine` flag requires User Profile read permission on your PAT. The command will continue without filtering if this fails.

### Shell completion not working

Make sure you've added the eval command to your shell config and restarted your terminal.

### Build stuck or need to cancel

```bash
ado-pipeline cancel <BUILD_ID> -y
```

## Development

### Setup

```bash
git clone https://github.com/SAGARSURI/adop.git
cd adop
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest tests/ -v
```

### Project Structure

```
src/ado_pipeline/
├── __init__.py      # Version
├── api.py           # Azure DevOps API client
├── cli.py           # CLI commands (click)
├── config.py        # Configuration management
├── favorites.py     # Favorites system
├── pipelines.py     # Pipeline definitions
└── plan.py          # Execution plan generation
```

## CI/CD

### Automated Testing

Tests run automatically on:
- Push to `main`
- Pull requests to `main`

Tests run against Python 3.10, 3.11, and 3.12.

[![CI](https://github.com/SAGARSURI/adop/actions/workflows/ci.yml/badge.svg)](https://github.com/SAGARSURI/adop/actions/workflows/ci.yml)

### Releasing

Releases are automated via GitHub Actions:

1. Update version in `pyproject.toml`
2. Commit and tag:
   ```bash
   git add pyproject.toml
   git commit -m "chore: bump version to X.Y.Z"
   git tag vX.Y.Z
   git push origin main --tags
   ```
3. The release workflow automatically:
   - Runs tests
   - Publishes to PyPI
   - Updates Homebrew tap

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.
