CLI tool for interacting with Azure DevOps.
Linux and macOS:
curl -sSL https://christianhelle.com/azdocli/install | bashWindows (PowerShell):
iwr -useb https://christianhelle.com/azdocli/install.ps1 | iexThese one-liner commands will automatically download and install the latest release for your platform.
You can also install azdocli using Cargo:
cargo install azdocliThis will install the azdocli binary, which you can use immediately.
On Linux systems with Snap support, you can install azdocli directly from the Snap Store:
snap install azdocliThis will install the latest stable version and automatically handle updates.
You can also download pre-built binaries from the GitHub Releases page:
- Windows:
windows-x64.ziporwindows-arm64.zip - macOS:
macos-x64.zipormacos-arm64.zip - Linux:
linux-x64.ziporlinux-arm64.zip
Extract the binary and add it to your PATH.
# 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>Before using the CLI, you need to create a Personal Access Token (PAT) in Azure DevOps:
-
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
- Sign in to your Azure DevOps organization (
-
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
By default azdocli targets the Azure DevOps cloud (https://dev.azure.com). You can log in to an enterprise or on-premises Azure DevOps installation by providing the server URL instead of a cloud organization name.
The stored base URL must not include the organization or collection segment. Provide the base URL including any application path (for example, https://devops.mycompany.com or https://tfs.mycompany.com/tfs) and then enter the organization/collection when prompted. You can also paste the full URL including the collection (for example, https://tfs.mycompany.com/tfs/DefaultCollection); the last path segment is treated as the organization/collection and is not stored as part of the base URL.
# Login to an enterprise Azure DevOps Server
azdocli login
# When prompted for organization, enter the server URL, for example:
# - https://devops.mycompany.com
# - https://tfs.mycompany.com/tfs/DefaultCollection
# Then enter the organization/collection name when prompted (not needed if it was part of the URL).The base URL is stored alongside your PAT, so all subsequent commands use that server. You can also create named profiles for cloud and enterprise servers side-by-side:
azdocli login --profile cloud
azdocli login --profile onpremNote: User entitlement management (azdocli user) is only supported against the default Azure DevOps cloud host. Commands that manage user licenses will fail with a clear message when a custom base URL is configured.
# 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
# List repositories
azdocli repos list
# List pipelines
azdocli pipelines listazdocli [SUBCOMMAND]
SUBCOMMANDS:
boards Manage Azure DevOps boards
login Login to Azure DevOps with a Personal Access Token (PAT)
logout Logout from Azure DevOps
migrate Migrate one or more team projects between organizations
pipelines Manage Azure DevOps pipelines
project Set or view the default project
repos Manage Azure DevOps repos
user Manage user entitlements
- Repository Management: List, create, delete, clone, view, browse and manage pull requests in repositories
- Pipeline Management: Manage Azure DevOps pipelines
- Project Management: Create, delete, list, and show Azure DevOps team projects, their teams, team members and process templates
- Migration: Cross-tenant team-project migration with
azdocli migrate(see src/README.md for the full guide) - 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
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
--projectto 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
The projects commands manage the team projects of your organization, and the teams inside them:
# 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 (administrators are marked)
azdocli projects members --team "MyProject Team"
# Or specify a project explicitly
azdocli projects members --team "MyProject Team" --project MyProject
# List the process templates, with the names and IDs accepted by projects create --process
azdocli projects processesTeam Project Features:
- Team discovery: List the teams of a project, optionally only your own
- Team membership: See who is on a team and which of them are administrators
- Process templates: Discover the processes available before creating a project
- Default project support: Use with default project or specify --project explicitly
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 8Clone 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
--yesflag for CI/CD scenarios - Parallel execution: Use
--parallelflag 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
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 MyProjectShow 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
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 --yesDelete Features:
- Soft delete by default: Repositories are moved to recycle bin and can be restored
- Hard delete option: Use
--hardflag for permanent deletion (may require manual cleanup) - Confirmation prompts: Interactive confirmation before deletion to prevent accidents
- Automation support: Skip prompts with
--yesflag 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
The repos branches, repos commits, repos files and repos file commands let you inspect the
contents of a repository without cloning it:
# 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 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
# 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 the contents of a single file
azdocli repos file --id MyRepository --path /README.md --branch developBrowsing Features:
- No clone required: Inspect branches, history and files straight from the CLI
- Server-side filtering: Branch, author, path and result limits are applied by Azure DevOps
- Default branch aware: Commands fall back to the repository default branch when
--branchis omitted - Pipe friendly:
repos filewrites the raw file contents to stdout
The repos pr commands allow you to manage pull requests within repositories:
# List active 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
# 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 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
# Open the pull request in a browser instead
azdocli repos pr show --repo MyRepository --id 123 --web# 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"
# 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 --reviewer bob@example.com \
--work-item 1234 --work-item 1235 --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 title and description (using default project)
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
# Or specify a project explicitly
azdocli repos pr update --repo MyRepository --id 123 --title "New title" --project MyProject# 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# 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 123Reviewers can be given as an email address, an identity ID, or @me for the
signed-in user.
# 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-authorValid votes are approve, approve-with-suggestions, reset, wait-for-author and reject.
Work items can also be linked when the pull request is created, with
repos pr create --work-item.
# List the linked work items with their type, state and title
azdocli repos pr work-item list --repo MyRepository --id 123
# Link one or more work items, repeating the flag or separating IDs with commas
azdocli repos pr work-item add --repo MyRepository --id 123 --work-item 42 --work-item 43
azdocli repos pr work-item add --repo MyRepository --id 123 --work-item 42,43
# Unlink a work item
azdocli repos pr work-item remove --repo MyRepository --id 123 --work-item 42A work item that is already linked is reported and skipped, so add can be run
again safely.
# 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-fixValid thread statuses are fixed, wont-fix, closed, by-design, active and pending.
Pull Request Features:
- Server-side filtering: List by state, author, reviewer, source branch or target branch
- Comprehensive details: Show displays status, draft flag, merge status, reviewers and their votes, labels, linked work items and open comment threads
- Branch specification: Specify source branch (required) and target branch (defaults to 'main')
- Flexible creation: Create pull requests with drafts, reviewers, linked work items, labels and auto-complete
- Flexible updates: Update pull request title and/or description (including from markdown file)
- Merge control: Complete with a chosen merge strategy, delete the source branch, or bypass policy with a recorded reason
- Review workflow: Add and remove reviewers, and cast votes, using email addresses, identity IDs or
@me - Discussion: Read threads, start file- and line-anchored comments, reply, and resolve
- Branch validation: Automatic formatting of branch names with refs/heads/ prefix
- Repository validation: Verify repository exists before creating or updating 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, unmergeable pull requests, or missing repositories
- Commit tracking: View all commits included in a pull request with detailed information
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 MyProjectList 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
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 MyProjectRuns 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
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 123Show Features:
- Detailed information: Run number, pipeline, state, result and timestamps
- Web link: The URL of the run in the Azure DevOps web interface
- Error handling: Helpful error messages when build not found
The pipelines run command queues 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 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=trueRun Features:
- Pipeline execution: Start a pipeline with a single command
- Branch selection: Queue the run against any branch with
--branch - Runtime variables: Set pipeline variables with repeatable
--variable NAME=VALUEarguments - Run summary: Prints the new run number, state and web URL
- Error handling: Clear feedback when pipeline cannot be started
The pipelines logs command lists the logs of a run, or prints one of them:
# 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 7Logs Features:
- Log inventory: See every log a run produced, with line counts and timestamps
- Full log text: Print a log to stdout so it can be piped, searched or saved
- Error handling: Clear feedback when the run or log does not exist
The pipelines artifacts command lists the artifacts a run published:
# List the artifacts of a run
azdocli pipelines artifacts --build-id 123
# Or specify a project explicitly
azdocli pipelines artifacts --build-id 123 --project MyProjectArtifacts Features:
- Artifact inventory: See every artifact published by a run
- Download URLs: Print the download URL of each artifact
- Error handling: Clear feedback when the run does not exist
The pipelines variable-group and pipelines service-connection commands inspect the resources a
pipeline consumes:
# 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 (secret values are never returned by Azure DevOps)
azdocli pipelines variable-group show --id 7
# 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-000000000000Library Features:
- Variable discovery: See which variable groups exist and what they define
- Secret safety: Secret variables are shown as
<secret>; the API never returns their values - Service connection inventory: List connections with their type and readiness, filtered by type
- Default project support: Use with default project or specify --project explicitly
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-deleteWork 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
--weboption - 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
The boards work-item comment commands read and write the discussion on a work item:
# 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"Comment Features:
- Read the discussion: See every comment with its author and timestamp
- Add comments: Post a comment from the command line or a script
- Safe rendering: Terminal control characters in remote text are escaped rather than executed
The boards work-item types command lists the work item types a project defines:
# List the work item types of the default project
azdocli boards work-item types
# Or specify a project explicitly
azdocli boards work-item types --project MyProjectThe boards query command runs any WIQL query and lists the work items it returns:
# 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 10Query Features:
- Arbitrary WIQL: Anything the Azure DevOps query editor accepts
- Full work item details: Results are shown in the same table as
work-item list - Result limits: Cap the number of work items fetched with
--limit
The project includes integration tests that verify the core repository management functionality against a real Azure DevOps instance.
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.jsonwith 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)
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 testThe 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
- The
test_config.jsonfile 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
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.