📖 User Guide

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

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

Set a default project

azdocli project MyDefaultProject

View the current default project

azdocli project

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

List the teams of a project

# List every team in the default project
azdocli projects teams

# Only the teams you belong to, capped at 10 results
azdocli projects teams --mine --top 10

List the members of a team

# Team administrators are marked in the listing
azdocli projects members --team "MyProject Team"

# With specific project
azdocli projects members --team "MyProject Team" --project MyProject

List the process templates

# The names and IDs accepted by projects create --process
azdocli projects processes

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

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

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

List Branches

# List the branches of a repository (the default branch is marked)
azdocli repos branches --id MyRepository

# Only show branches matching some text, and cap the number of results
azdocli repos branches --id MyRepository --filter feature --top 20

List Commits

# List the 25 most recent commits on the default branch
azdocli repos commits --id MyRepository

# Read the history of a specific branch, author or path
azdocli repos commits --id MyRepository --branch develop --author "Christian Helle" --path src --top 50

Browse Files

# List the files and folders at the root of the repository
azdocli repos files --id MyRepository

# List a subfolder, on a specific branch, recursively
azdocli repos files --id MyRepository --path /src --branch develop --recursive

Print a File

# Print the contents of a single file
azdocli repos file --id MyRepository --path /README.md --branch develop

List Pull Requests

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

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

# Filter by state - active (the default), completed, abandoned, or all
azdocli repos pr list --repo MyRepository --status completed

# Filter by author, reviewer or branch, and cap the number of results
azdocli repos pr list --repo MyRepository --creator @me
azdocli repos pr list --repo MyRepository --reviewer alice@example.com
azdocli repos pr list --repo MyRepository --source "feature/my-feature" --target main
azdocli repos pr list --repo MyRepository --top 10

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

# Open the pull request in a browser instead
azdocli repos pr show --repo MyRepository --id 123 --web

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"

# Open as a draft, with reviewers, linked work items and labels
azdocli repos pr create --repo MyRepository --source "feature/my-feature" --title "My Feature" --draft --reviewer alice@example.com --work-item 1234 --label "needs-review"

# Merge automatically once policies pass, then delete the source branch
azdocli repos pr create --repo MyRepository --source "feature/my-feature" --title "My Feature" --auto-complete --delete-source-branch

Update Pull Request

# Update title and description
azdocli repos pr update --repo MyRepository --id 123 --title "New title" --description "New description"

# Update title only
azdocli repos pr update --repo MyRepository --id 123 --title "New title"

# Update description from markdown file
azdocli repos pr update --repo MyRepository --id 123 --description-file ./description.md

# Update both with file description
azdocli repos pr update --repo MyRepository --id 123 --title "New title" --description-file ./description.md

# With specific project
azdocli repos pr update --repo MyRepository --id 123 --title "New title" --project MyProject

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

Complete, Abandon or Reactivate a Pull Request

# Merge the pull request, squashing the source commits and deleting the branch
azdocli repos pr complete --repo MyRepository --id 123 --merge-strategy squash --delete-source-branch

# Merge without the confirmation prompt (for CI/CD)
azdocli repos pr complete --repo MyRepository --id 123 --yes

# Set the pull request to complete automatically once policies pass
azdocli repos pr complete --repo MyRepository --id 123 --auto-complete --yes

# Complete despite failing branch policies, recording a reason
azdocli repos pr complete --repo MyRepository --id 123 --bypass-policy --bypass-reason "hotfix"

# Close a pull request without merging, and reopen it later
azdocli repos pr abandon --repo MyRepository --id 123 --yes
azdocli repos pr reactivate --repo MyRepository --id 123

Merge strategies are no-fast-forward, squash, rebase and rebase-merge.

Manage Reviewers

# List reviewers with their votes
azdocli repos pr reviewers list --repo MyRepository --id 123

# Add one or more reviewers, optionally as required reviewers
azdocli repos pr reviewers add --repo MyRepository --id 123 --reviewer alice@example.com --reviewer bob@example.com
azdocli repos pr reviewers add --repo MyRepository --id 123 --reviewer alice@example.com --required

# Remove a reviewer
azdocli repos pr reviewers remove --repo MyRepository --id 123 --reviewer alice@example.com

# Cast your own vote
azdocli repos pr reviewers vote --repo MyRepository --id 123 --vote approve
azdocli repos pr reviewers vote --repo MyRepository --id 123 --vote wait-for-author

Reviewers can be given as an email address, an identity ID, or @me for the signed-in user. Valid votes are approve, approve-with-suggestions, reset, wait-for-author and reject.

Read and Write Comments

# Read the discussion (system-generated threads are hidden unless --all is given)
azdocli repos pr threads --repo MyRepository --id 123
azdocli repos pr threads --repo MyRepository --id 123 --all

# Start a new thread
azdocli repos pr comment add --repo MyRepository --id 123 --message "Looks good to me"

# Start a thread anchored to a file and line
azdocli repos pr comment add --repo MyRepository --id 123 --message "Needs a null check" --file "/src/main.rs" --line 42

# Reply to an existing thread, then resolve it
azdocli repos pr comment reply --repo MyRepository --id 123 --thread 7 --message "Fixed in the latest push"
azdocli repos pr comment resolve --repo MyRepository --id 123 --thread 7
azdocli repos pr comment resolve --repo MyRepository --id 123 --thread 7 --status wont-fix

Valid thread statuses are fixed, wont-fix, closed, by-design, active and pending.

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

# Run a specific branch
azdocli pipelines run --id 42 --branch develop

# Pass pipeline variables (repeat --variable for more than one)
azdocli pipelines run --id 42 --variable environment=staging --variable verbose=true

Features: Queue a run against any branch, set runtime variables, and print the new run number, state and web URL.

Pipeline Logs

# List the logs produced by a run
azdocli pipelines logs --id 42 --build-id 123

# Print the contents of a single log
azdocli pipelines logs --id 42 --build-id 123 --log-id 7

Features: See every log a run produced with line counts and timestamps, or print one log to stdout so it can be piped, searched or saved.

Variable Groups

# List the variable groups of the default project
azdocli pipelines variable-group list

# Filter by name and cap the number of results
azdocli pipelines variable-group list --name "release" --top 10

# Show a variable group and its variables
azdocli pipelines variable-group show --id 7

Features: See which variable groups exist and what they define. Secret variables are shown as <secret>, since Azure DevOps never returns their values.

Service Connections

# List the service connections of the default project
azdocli pipelines service-connection list

# Only connections of one type
azdocli pipelines service-connection list --type azurerm

# Show a single service connection
azdocli pipelines service-connection show --id 00000000-0000-0000-0000-000000000000

Features: List connections with their type and readiness, filtered by type, or show one in full.

Pipeline Artifacts

# List the artifacts of a run
azdocli pipelines artifacts --build-id 123

# With specific project
azdocli pipelines artifacts --build-id 123 --project MyProject

Features: List every artifact a run published, with its type and download URL.

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

Read and Add Comments

# List the comments on a work item
azdocli boards work-item comment list --id 123

# Only show the most recent comments
azdocli boards work-item comment list --id 123 --top 5

# Add a comment
azdocli boards work-item comment add --id 123 --message "Reproduced on the staging build"

Features: See every comment with its author and timestamp, post comments from scripts, and have terminal control characters in remote text escaped rather than executed.

List Work Item Types

# List the work item types of the default project
azdocli boards work-item types

# With specific project
azdocli boards work-item types --project MyProject

Run a Query

# Run a WIQL query against the default project
azdocli boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'"

# Cap the number of results
azdocli boards query --wiql "SELECT [System.Id] FROM WorkItems" --limit 10

Features: Anything the Azure DevOps query editor accepts, rendered in the same table as work-item list, with a configurable result limit.

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

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

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>