Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install azdocli

It will make the azdocli command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall azdocli uninstalls.

Back to the crate overview.

Readme

Azure DevOps CLI

CLI tool for interacting with Azure DevOps.

Features

Repository Management: List, create, delete, clone, view, and manage pull requests in repositories
Pipeline Management: Manage Azure DevOps pipelines
Board Management: Manage Azure DevOps boards
Authentication: Secure login using Personal Access Tokens (PAT)
Default Project: Set a default project to avoid specifying --project for every command

Default Project Management

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

# All commands will now use the default project if --project is not specified
azdocli repos list                  # Uses default project
azdocli pipelines list              # Uses default project
azdocli repos list --project Other  # Overrides default with "Other"

Default 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 Features

Repository Clone Feature

The repos clone command allows you to clone all repositories from an Azure DevOps project:

# Set a default project first (optional but recommended)
azdocli project MyProject

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

# Or override with a specific project
azdocli repos clone --project MyProject

# Clone to a 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 the number of concurrent clone 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 Show Feature

The repos show command displays detailed information about a specific repository:

# Show details of a repository by name (using default project)
azdocli repos show --id MyRepository

# Or specify a project explicitly
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 Delete Feature

The repos delete command allows you to delete repositories from an Azure DevOps project:

# Soft delete a repository by name (using default project) - moves to recycle bin
azdocli repos delete --id MyRepository

# Or specify a project explicitly
azdocli repos delete --id MyRepository --project MyProject

# Hard delete - permanently delete after soft delete (requires manual recycle bin cleanup)
azdocli repos delete --id MyRepository --hard

# Skip confirmation prompt (useful for 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 (may require manual cleanup)
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
Default project support: Use with default project or specify --project explicitly

Pull Request Management Features

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

List Pull Requests

# List all pull requests for a repository (using default project)
azdocli repos pr list --repo MyRepository

# Or specify a project explicitly
azdocli repos pr list --repo MyRepository --project MyProject

Show Pull Request Details

# Show details of a specific pull request (using default project)
azdocli repos pr show --repo MyRepository --id 123

# Or specify a project explicitly
azdocli repos pr show --repo MyRepository --id 123 --project MyProject

Create Pull Request

# Create a new pull request with source and target branches (using default project)
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"

# Or specify a project explicitly
azdocli repos pr create --repo MyRepository --source "feature/my-feature" --target "develop" --title "My Feature" --description "Description" --project MyProject

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

Show Pull Request Commits

# Show commits in a specific pull request (using default project)
azdocli repos pr commits --repo MyRepository --id 123

# Or specify a project explicitly
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
Default project support: Use with default project or specify --project explicitly
Error handling: Clear feedback for invalid pull request IDs or missing repositories
Commit tracking: View all commits included in a pull request with detailed information

Pipeline Management Features

Pipeline List Feature

The pipelines list command allows you to list all pipelines in an Azure DevOps project:

# List all pipelines in the default project
azdocli pipelines list

# Or specify a project explicitly
azdocli pipelines list --project MyProject

List Features:

Comprehensive listing: View all pipelines in a project with IDs and names
User-friendly formatting: Easy-to-read table format
Error handling: Helpful error messages when project not found or access denied

Pipeline Runs Feature

The pipelines runs command shows all builds (runs) of a specified pipeline:

# Show all runs for a pipeline (using default project)
azdocli pipelines runs --id 42

# Or specify a project explicitly
azdocli pipelines runs --id 42 --project MyProject

Runs Features:

Run history: View all runs for a specific pipeline
Status visibility: See current state and result of each pipeline run
User-friendly formatting: Clear display of run information

Pipeline Show Feature

The pipelines show command displays detailed information about a specific pipeline build:

# Show details of a specific pipeline build (using default project)
azdocli pipelines show --id 42 --build-id 123

# Or specify a project explicitly
azdocli pipelines show --id 42 --project MyProject --build-id 123

Show Features:

Detailed information: Comprehensive details about a specific pipeline build
Debug information: Access to internal state for troubleshooting purposes
Error handling: Helpful error messages when build not found

Pipeline Run Feature

The pipelines run command starts a new pipeline run:

# Run a pipeline (using default project)
azdocli pipelines run --id 42

# Or specify a project explicitly
azdocli pipelines run --id 42 --project MyProject

Run Features:

Pipeline execution: Start a pipeline with a single command
Live updates: See details of the running build in real-time
Error handling: Clear feedback when pipeline cannot be started

Board Management Features

Work Item Management

The boards work-item commands allow you to manage work items in an Azure DevOps project:

# List work items assigned to me (using default project)
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

# Show details of a specific work item (using default project)
azdocli boards work-item show --id 123

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

# Or specify a project explicitly
azdocli boards work-item show --id 123 --project MyProject

# Create a new work item (using default project)
# Supported types: bug, task, user-story, feature, epic
azdocli boards work-item create bug --title "Fix login issue" --description "Users cannot login after password change"

# Update a work item (using default project)
azdocli boards work-item update --id 123 --title "New title" --state "Active" --priority 2

# Delete a work item permanently (using default project)
azdocli boards work-item delete --id 123

# Soft delete a work item by changing 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 filtering options
Multiple work item types: Support for bug, task, user story, feature, and epic
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

CLI tool for interacting with Azure DevOps

USAGE:
    azdocli [SUBCOMMAND]

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    boards       Manage Azure DevOps boards
    help         Print this message or the help of the given subcommand(s)
    login        Login to Azure DevOps with a Personal Access Token (PAT)
    logout       Logout from Azure DevOps
    pipelines    Manage Azure DevOps pipelines
    repos        Manage Azure DevOps repos

Installation

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 will automatically download and install the latest release for your platform.

Install from crates.io

You can also install azdocli using Cargo:

cargo install azdocli

This will install the azdocli binary, which you can use immediately.

Install using Snap (Linux)

On Linux systems with Snap support, you can install azdocli directly from the Snap Store:

snap install azdocli

This will install the latest stable version and automatically handle updates.

Install from GitHub Releases

You can also download pre-built binaries from the GitHub Releases page:

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

Extract the binary and add it to your PATH.

Authentication Setup

Before using the CLI, you need to create a Personal Access Token (PAT) in Azure DevOps:

Creating a Personal Access Token

Navigate to Azure DevOps:
- Sign in to your Azure DevOps organization (https://dev.azure.com/{yourorganization})
- Click on your profile picture in the top right corner
- Select Personal Access Tokens
Create New Token:
- Click + New Token
- Enter a descriptive name (e.g., "azdocli-token")
- Select your organization
- Set expiration date (recommended: 90 days or less)
Configure 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)
Save Your Token:
- Click Create
- ⚠️ Important: Copy the token immediately and store it securely
- 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

Usage

First, login to Azure DevOps using the PAT you created:

# Login with your Personal Access Token
azdocli login
# You'll be prompted for:
# - Organization name (e.g., "mycompany" from https://dev.azure.com/mycompany)
# - Personal Access Token (the PAT you created above)

# Set a default project (optional but recommended)
azdocli project MyProject

Basic Examples

# Repository management
azdocli repos list                           # List all repositories
azdocli repos show --id MyRepo               # Show repository details
azdocli repos clone                          # Clone all repositories

# Pull request management
azdocli repos pr list --repo MyRepo          # List pull requests for a repository
azdocli repos pr show --repo MyRepo --id 123 # Show pull request details
azdocli repos pr create --repo MyRepo --source "feature/my-feature" --title "My Feature" # Create a new pull request

# Pipeline management
azdocli pipelines list                       # List all pipelines
azdocli pipelines runs --id 42               # Show pipeline runs
azdocli pipelines show --id 42 --build-id 123 # Show build details

For detailed examples and features, see the respective sections below.

Building from Source

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

Testing

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

Setting up Test Configuration

To run the integration tests, you need to create a test configuration file with your Azure DevOps credentials:

Copy the template file:

cp test_config.json.template test_config.json

Edit test_config.json with your Azure DevOps details:

 {
   "organization": "your-organization-name",
   "pat": "your-personal-access-token",
   "project": "your-test-project-name"
 }

Make sure you have:
- A valid Azure DevOps Personal Access Token (PAT) with repository permissions
- Access to an Azure DevOps project where you can create/delete test repositories
- Git installed and available in your PATH (for clone testing)

Running Tests

The integration tests are marked with #[ignore] by default to prevent accidental execution without proper configuration.

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

# Run only the repository smoke tests
cargo test test_create_show_clone_delete_repository -- --ignored

# Run the repository listing test
cargo test test_list_repositories -- --ignored

# Run regular unit tests only (currently none)
cargo test

Test Coverage

The integration tests cover the following repository operations:

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

⚠️ Important: The tests create and delete actual repositories in your Azure DevOps project. Make sure to use a test project and not a production environment.

Security Notes

The test_config.json file is automatically ignored by Git to prevent accidental credential commits
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 for running these tests

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on:

Code style and patterns
Development setup
Testing procedures
PR description requirements
How to keep documentation updated

Please ensure your PR descriptions are verbose and follow the guidelines in CONTRIBUTING.md.