Azure DevOps

Interact with Azure DevOps Services using the azdevops CLI. All commands output JSON by default for reliable parsing.

Setup

Configure once (credentials saved to ~/.config/azdevops-cli/config.json):

azdevops setup --org myorg --token <personal-access-token> --project MyProject

Or use environment variables (these take priority over the config file):

export AZDEVOPS_ORG=myorg
export AZDEVOPS_TOKEN=<personal-access-token>
export AZDEVOPS_PROJECT=MyProject

The --project / AZDEVOPS_PROJECT is optional — it sets a default project so you don't need to pass --project on every command.

Projects

azdevops project list --format json --pretty

Repositories

azdevops repo list --project MyProject --format json --pretty

Branches

azdevops branch list --repo my-repo --format json
azdevops branch list --repo my-repo --filter "feature/" --format json

Pull Requests

List PRs

azdevops pr list --repo my-repo --format json --pretty
azdevops pr list --repo my-repo --status active --top 10 --format json

Status options: active, completed, abandoned, all (default: active).

Get a single PR

azdevops pr get --repo my-repo --id 42 --format json --pretty

Create a PR

azdevops pr create --repo my-repo --source feature/login --target main --title "Add login page" --description "Details here" --format json
azdevops pr create --repo my-repo --source feature/login --target main --title "Add login page" --reviewers "id1,id2" --format json

Update a PR

azdevops pr update --repo my-repo --id 42 --status completed --format json
azdevops pr update --repo my-repo --id 42 --title "Updated title" --format json

List reviewers

azdevops pr reviewers --repo my-repo --id 42 --format json --pretty

Reviewer vote codes: 10=Approved, 5=Approved with suggestions, 0=No vote, -5=Waiting for author, -10=Rejected.

Pipelines

List pipelines

azdevops pipeline list --format json --pretty

Trigger a pipeline run

azdevops pipeline run --pipeline-id 5 --format json
azdevops pipeline run --pipeline-id 5 --branch feature/login --format json

List runs for a pipeline

azdevops pipeline runs --pipeline-id 5 --top 10 --format json --pretty

Get a specific run

azdevops pipeline run-get --pipeline-id 5 --run-id 123 --format json --pretty

Work Items

Get a work item

azdevops work-item get --id 1234 --format json --pretty
azdevops work-item get --id 1234 --expand relations --format json

Expand options: none, relations, fields, links, all.

Create a work item

azdevops work-item create --type Bug --title "Login fails on timeout" --description "Steps to reproduce..." --format json
azdevops work-item create --type Task --title "Update dependencies" --assigned-to "John Smith" --format json

Common types: Bug, Task, User Story, Feature, Epic.

Update a work item

azdevops work-item update --id 1234 --state "In Progress" --format json
azdevops work-item update --id 1234 --title "New title" --assigned-to "Jane Doe" --format json

Query work items (WIQL)

azdevops work-item query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active' AND [System.AssignedTo] = @Me" --format json --pretty
azdevops work-item query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] <> 'Closed'" --top 20 --format json

Newlines in arguments

The CLI accepts real newlines in argument values. Do NOT use literal \n escape sequences — they will be passed through as the two characters \ and n, not as actual line breaks.

To include newlines in --description, --title, or any other argument, use a shell heredoc or ANSI-C quoting:

Correct — ANSI-C quoting (bash $'...'):

azdevops pr create --repo my-repo --source feature/x --target main --title 'Feature X' --description $'First line.\n\nSecond paragraph.\n\nThird paragraph.' --format json

Correct — heredoc via command substitution:

azdevops pr create --repo my-repo --source feature/x --target main --title 'Feature X' --description "$(cat <<'EOF'
First line.

Second paragraph.

Third paragraph.
EOF
)" --format json

Wrong — literal backslash-n (will NOT produce newlines):

# BAD: \n is passed as literal text, not a newline
azdevops pr create --repo my-repo --source feature/x --target main --title 'Feature X' --description 'First line.\n\nSecond paragraph.' --format json

Wrong — double-escaped (will NOT produce newlines):

# BAD: \\n is passed as literal text
azdevops pr create --repo my-repo --source feature/x --target main --title 'Feature X' --description 'First line.\\n\\nSecond paragraph.' --format json

Output format

All commands support --format json (compact) or --format text (human-readable tables). Add --pretty for indented JSON.

Exit codes: 0 = success, 1 = error. Errors are written to stderr as JSON.

Common workflows

Triage a bug:

azdevops work-item query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'New'" --top 5 --format json
azdevops work-item update --id 1234 --state "Active" --assigned-to "Jane Doe"

Create a PR and trigger a build:

azdevops pr create --repo my-repo --source feature/x --target main --title "Feature X" --format json
azdevops pipeline run --pipeline-id 5 --branch feature/x --format json