adop-cli 0.1.9

CLI tool to trigger Azure DevOps pipelines

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)

brew tap SAGARSURI/tap
brew install adop-cli

pip

pip install adop-cli

From Source

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

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:

# 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 - 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

# 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:

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:

# 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

# 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

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

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

Cancel a Build

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

Open Build in Browser

ado-pipeline open <BUILD_ID>

Compare Two Builds

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

ado-pipeline pipeline list

Add a Pipeline

# 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

# Interactive import from remote
ado-pipeline pipeline import

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

View Pipeline Parameters

# 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

# 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

ado-pipeline pipeline remove <alias>

Favorites

Save frequently used build configurations for quick access.

Save a Favorite

# 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

ado-pipeline fav list

Run a Favorite

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

Remove a Favorite

ado-pipeline fav remove quick-build

Configuration

# 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:

# 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:

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:

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

ado-pipeline cancel <BUILD_ID> -y

Development

Setup

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

Running Tests

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.

Releasing

Releases are automated via GitHub Actions:

1. Update version in pyproject.toml
2. Commit and tag:

   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 for guidelines.

License

MIT License - see LICENSE for details.