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

📦 Installation

Installation Methods

Choose the installation method that works best for your system:

From crates.io (Recommended)

cargo install azdocli

This is the easiest way to install azdocli. 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.

📁 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

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

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