User Guide - Azure DevOps CLI

## 🚀 Getting Started

Azure DevOps CLI (azdocli) provides a powerful command-line interface for interacting with Azure DevOps services. This guide covers all features and commands available in the tool.

## 📦 Installation

### Installation Methods

Choose the installation method that works best for your system:

#### 🚀 Quick Install (Recommended)

Linux and macOS:

    curl -sSL https://christianhelle.com/azdocli/install | bash

Windows (PowerShell):

    iwr -useb https://christianhelle.com/azdocli/install.ps1 | iex

These one-liner commands automatically download and install the latest release for your platform.

#### From crates.io

    cargo install azdocli

Install using Cargo. It requires Rust and Cargo to be installed on your system.

#### Using Snap (Linux)

    snap install azdocli

On Linux systems with Snap support, you can install azdocli directly from the Snap Store. This method provides automatic updates and easy installation.

#### From GitHub Releases

Download pre-built binaries for your platform:

- Windows: `windows-x64.zip` or `windows-arm64.zip`
- macOS: `macos-x64.zip` or `macos-arm64.zip`
- Linux: `linux-x64.zip` or `linux-arm64.zip`

Visit the GitHub Releases page to download the latest version.

Extract the binary from the downloaded archive and add it to your system's PATH.

## 🔐 Authentication

### Creating a Personal Access Token (PAT)

Before using any commands, you need to authenticate with Azure DevOps using a Personal Access Token (PAT). Follow these steps to create one:

#### Step 1: Navigate to Personal Access Tokens

1. Sign in to your Azure DevOps organization (`https://dev.azure.com/{yourorganization}`)
2. Click on your profile picture in the top right corner
3. Select Personal Access Tokens from the dropdown menu

#### Step 2: Create New Token

1. Click + New Token
2. Enter a descriptive name (e.g., "azdocli-token")
3. Select your organization
4. Set expiration date (recommended: 90 days or less)
5. Configure the required scopes:

##### Required Scopes:

- Code: Read & write (for repository operations)
- Build: Read & execute (for pipeline operations)
- Work Items: Read & write (for board operations)
- Project and Team: Read (for project operations)

#### Step 3: Save Your Token

1. Click Create
2. ⚠️ Important: Copy the token immediately and store it securely
3. The token will not be shown again

Security Best Practices:

- Never commit your PAT to version control
- Use environment variables or secure storage for automation
- Regularly rotate your tokens
- Use the minimum required permissions

### Login and Logout

Once you have your Personal Access Token, you can authenticate with the CLI.

#### Login to Azure DevOps

    azdocli login

This command will prompt you to enter:

- Azure DevOps organization name: Just the organization name (e.g., "mycompany" from https://dev.azure.com/mycompany)
- Personal Access Token: The PAT you created in the previous steps

The CLI will validate your credentials and store them securely for future use.

#### Logout from Azure DevOps

    azdocli logout

Clears stored credentials and logs you out of Azure DevOps.

## 📁 Projects and Default Project Management

### Project Commands

The project command allows you to set and view a default project, eliminating the need to specify --project for every command.

#### Set a default project

    azdocli project MyDefaultProject

#### View the current default project

    azdocli project

### Project Management Commands

Manage team projects in your Azure DevOps organization with the `projects` command group.

#### List projects

    azdocli projects list

#### Show a project

    azdocli projects show --project MyProject

#### Create a project

    azdocli projects create --name MyProject --description "Team workspace" --process Agile --source-control git --visibility private

#### Delete a project

    azdocli projects delete --id 00000000-0000-0000-0000-000000000000 --yes

Note: `azdocli projects` commands are organization-scoped and rely on your stored credentials from `azdocli login`.

#### Features:

- Persistent storage: Default project is saved in your user configuration
- Optional override: Use --project to override the default for any command
- All modules supported: Works with repos, pipelines, boards, and projects
- Helpful error messages: Clear feedback when no default is set and no --project is provided

## 📦 Repository Management

### Basic Repository Operations

#### List all repositories

    # List repositories in default project
    azdocli repos list

    # List repositories in specific project
    azdocli repos list --project MyProject

#### Create a new repository

    # Create repository in default project
    azdocli repos create --name MyNewRepo

    # Create repository in specific project
    azdocli repos create --name MyNewRepo --project MyProject

#### Show repository details

    # Show details using default project
    azdocli repos show --id MyRepository

    # Show details with specific project
    azdocli repos show --id MyRepository --project MyProject

#### Show Features:

- Comprehensive details: View repository name, ID, URLs, size, and metadata
- User-friendly formatting: Emoji icons and formatted output for better readability
- Clone URLs: Display both HTTPS and SSH clone URLs
- File size formatting: Automatic conversion to KB/MB for better readability
- Error handling: Helpful error messages with suggestions when repository not found

### Repository Clone Feature

The repos clone command allows you to clone all repositories from an Azure DevOps project with powerful options for automation and parallel processing.

#### Basic cloning

    # Clone all repositories from default project (with confirmation prompt)
    azdocli repos clone

    # Clone from specific project
    azdocli repos clone --project MyProject

#### Advanced cloning options

    # Clone to specific directory
    azdocli repos clone --target-dir ./repos

    # Skip confirmation prompt (useful for automation)
    azdocli repos clone --yes

    # Clone repositories in parallel for faster execution
    azdocli repos clone --parallel

    # Control concurrent operations (default: 4, max: 8)
    azdocli repos clone --parallel --concurrency 6

    # Combine all options for maximum efficiency
    azdocli repos clone --target-dir ./repos --yes --parallel --concurrency 8

#### Clone Features:

- Bulk cloning: Clone all repositories from a project with a single command
- Target directory: Specify where to clone repositories (defaults to current directory)
- Confirmation prompts: Interactive confirmation with repository listing before cloning
- Automation support: Skip prompts with --yes flag for CI/CD scenarios
- Parallel execution: Use --parallel flag to clone multiple repositories simultaneously
- Concurrency control: Adjust the number of concurrent operations with --concurrency (1-8)
- Error handling: Comprehensive error reporting for failed clones
- Progress tracking: Real-time feedback on clone operations

### Repository Delete Feature

The repos delete command allows you to delete repositories from an Azure DevOps project with safety features.

#### Delete operations

    # Soft delete (moves to recycle bin)
    azdocli repos delete --id MyRepository

    # Specify project explicitly
    azdocli repos delete --id MyRepository --project MyProject

    # Hard delete (permanent deletion)
    azdocli repos delete --id MyRepository --hard

    # Skip confirmation prompt (automation)
    azdocli repos delete --id MyRepository --yes

    # Combine options for automated hard delete
    azdocli repos delete --id MyRepository --hard --yes

#### Delete Features:

- Soft delete by default: Repositories are moved to recycle bin and can be restored
- Hard delete option: Use --hard flag for permanent deletion
- Confirmation prompts: Interactive confirmation before deletion to prevent accidents
- Automation support: Skip prompts with --yes flag for CI/CD scenarios
- Repository validation: Verify repository exists before attempting deletion
- Error handling: Clear feedback when repository not found or access denied

### Pull Request Management

The repos pr commands allow you to manage pull requests within repositories.

#### List Pull Requests

    # List all pull requests for a repository
    azdocli repos pr list --repo MyRepository

    # With specific project
    azdocli repos pr list --repo MyRepository --project MyProject

#### Show Pull Request Details

    # Show details of a specific pull request
    azdocli repos pr show --repo MyRepository --id 123

    # With specific project
    azdocli repos pr show --repo MyRepository --id 123 --project MyProject

#### Create Pull Request

    # Create with full details
    azdocli repos pr create --repo MyRepository --source "feature/my-feature" --target "main" --title "My Feature" --description "Description"

    # Create with minimal information (target defaults to 'main')
    azdocli repos pr create --repo MyRepository --source "feature/my-feature" --title "My Feature"

    # With specific project
    azdocli repos pr create --repo MyRepository --source "feature/my-feature" --target "develop" --title "My Feature" --project MyProject

    # Source branch is required, target defaults to 'main'
    azdocli repos pr create --repo MyRepository --source "bugfix/fix-login"

#### Show Pull Request Commits

    # Show commits in a specific pull request
    azdocli repos pr commits --repo MyRepository --id 123

    # With specific project
    azdocli repos pr commits --repo MyRepository --id 123 --project MyProject

#### Pull Request Features:

- Repository filtering: List shows only pull requests for the specified repository
- Comprehensive details: Show command displays ID, title, description, status, branches, and creation date
- Branch specification: Specify source branch (required) and target branch (defaults to 'main')
- Flexible creation: Create pull requests with or without title/description
- Branch validation: Automatic formatting of branch names with refs/heads/ prefix
- Repository validation: Verify repository exists before creating pull request
- Authentication handling: Proper error messages when not logged in
- Error handling: Clear feedback for invalid pull request IDs or missing repositories
- Commit tracking: View all commits included in a pull request with detailed commit information, messages, and author details

## 🔧 Pipeline Management

### Pipeline Commands

#### List Pipelines

    # List all pipelines in default project
    azdocli pipelines list

    # List pipelines in specific project
    azdocli pipelines list --project MyProject

Features: Comprehensive listing with IDs and names in user-friendly table format.

#### Show Pipeline Runs

    # Show all runs for a pipeline
    azdocli pipelines runs --id 42

    # With specific project
    azdocli pipelines runs --id 42 --project MyProject

Features: View run history, status visibility, and clear display of run information.

#### Show Pipeline Build Details

    # Show details of a specific pipeline build
    azdocli pipelines show --id 42 --build-id 123

    # With specific project
    azdocli pipelines show --id 42 --project MyProject --build-id 123

Features: Detailed information about builds, debug information for troubleshooting.

#### Run Pipeline

    # Start a new pipeline run
    azdocli pipelines run --id 42

    # With specific project
    azdocli pipelines run --id 42 --project MyProject

Features: Pipeline execution with real-time updates and clear error feedback.

## 📋 Board Management

### Work Item Management

The boards work-item commands allow you to manage work items in an Azure DevOps project with full CRUD operations and advanced filtering capabilities.

#### List My Work Items

    # List work items assigned to me
    azdocli boards work-item list

    # List work items with filters
    azdocli boards work-item list --state "Active" --work-item-type "Bug" --limit 20

    # Or specify a project explicitly
    azdocli boards work-item list --project MyProject

    # Advanced filtering examples
    azdocli boards work-item list --state "New" --limit 10
    azdocli boards work-item list --work-item-type "User Story" --state "Active"

Features: View work items assigned to you with filtering by state, work item type, and configurable result limits.

#### Show Work Item

    # Show details of a work item
    azdocli boards work-item show --id 123

    # Open work item directly in web browser
    azdocli boards work-item show --id 123 --web

    # With specific project
    azdocli boards work-item show --id 123 --project MyProject

#### Create Work Item

    # Create different types of work items
    azdocli boards work-item create bug --title "Fix login issue" --description "Users cannot login after password change"
    azdocli boards work-item create task --title "Update documentation"
    azdocli boards work-item create user-story --title "User registration feature"
    azdocli boards work-item create feature --title "New reporting dashboard"
    azdocli boards work-item create epic --title "Mobile application development"

Supported types: bug, task, user-story, feature, epic

#### Update Work Item

    # Update work item fields
    azdocli boards work-item update --id 123 --title "New title" --state "Active" --priority 2

#### Delete Work Item

    # Permanent delete
    azdocli boards work-item delete --id 123

    # Soft delete (changes state to "Removed")
    azdocli boards work-item delete --id 123 --soft-delete

#### Work Item Features:

- Full CRUD operations: Create, read, update, and delete work items
- List my work items: View work items assigned to you with advanced filtering options
- Multiple work item types: Support for bug, task, user story, feature, and epic
- Advanced filtering: Filter by state, work item type, and limit number of results
- Web integration: Open work items directly in browser with --web option
- Soft delete: Option to change state to "Removed" instead of permanent deletion
- Field updates: Update title, description, state, and priority
- Default project support: Use with default project or specify --project explicitly
- Error handling: Clear feedback when work item not found or access denied
- WIQL integration: Uses Azure DevOps Work Item Query Language for efficient data retrieval

## 🧪 Testing

### Integration Tests

The project includes integration tests that verify core functionality against a real Azure DevOps instance.

#### Setting up Test Configuration

Create a test configuration file:

    # Copy the template
    cp test_config.json.template test_config.json

    # Edit with your Azure DevOps details
    {
      "organization": "your-organization-name",
      "pat": "your-personal-access-token",
      "project": "your-test-project-name"
    }

#### Running Tests

    # Run all tests including integration tests
    cargo test -- --ignored

    # Run specific repository tests
    cargo test test_create_show_clone_delete_repository -- --ignored

    # Run regular unit tests only
    cargo test

#### Test Coverage:

- Create: Creates new repositories in your Azure DevOps project
- Show: Retrieves and verifies repository details
- Clone: Attempts to clone repositories to temporary directory
- Delete: Performs hard delete to clean up test repositories

#### Security Notes

- The test_config.json file is automatically ignored by Git
- Store your PAT securely and never commit it to version control
- Use a PAT with minimal required permissions (repository read/write)
- Consider using a dedicated test organization or project

## 🔨 Building from Source

### Development Setup

#### Build Process

    # Clone the repository
    git clone https://github.com/christianhelle/azdocli.git
    cd azdocli

    # Build the project
    cargo build

    # Run tests
    cargo test

    # Run the CLI
    cargo run -- <command>