📖 User Guide

Complete guide to Azure DevOps CLI features and commands

🚀 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.

🔐 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

ado 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

ado logout

Clears stored credentials and logs you out of Azure DevOps.

📁 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

ado project MyDefaultProject

View the current default project

ado project

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, and boards
  • 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
ado repos list

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

Create a new repository

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

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

Show repository details

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

# Show details with specific project
ado 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)
ado repos clone

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

Advanced cloning options

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

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

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

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

# Combine all options for maximum efficiency
ado 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)
ado repos delete --id MyRepository

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

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

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

# Combine options for automated hard delete
ado 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
ado repos pr list --repo MyRepository

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

Show Pull Request Details

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

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

Create Pull Request

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

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

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

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

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

🔧 Pipeline Management

Pipeline Commands

List Pipelines

# List all pipelines in default project
ado pipelines list

# List pipelines in specific project
ado 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
ado pipelines runs --id 42

# With specific project
ado 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
ado pipelines show --id 42 --build-id 123

# With specific project
ado 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
ado pipelines run --id 42

# With specific project
ado 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.

Show Work Item

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

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

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

Create Work Item

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

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

Update Work Item

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

Delete Work Item

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

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

Work Item Features:

  • Full CRUD operations: Create, read, update, and delete work items
  • Multiple work item types: Support for bug, task, user story, feature, and epic
  • 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

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