Skip to content
adtk

Quick Start

1. Authenticate

Section titled “1. Authenticate”
Terminal window
# Interactive (stores credentials locally)
adtk auth


# Or via environment variables
export AZURE_DEVOPS_ORG=myorg
export AZURE_DEVOPS_PAT=your-pat-here

2. List Projects

Section titled “2. List Projects”
Terminal window
adtk projects list

Output:

NAME              ID                                     STATE
MyProject         a1b2c3d4-e5f6-7890-abcd-ef1234567890   wellFormed
AnotherProject    b2c3d4e5-f6a7-8901-bcde-f12345678901   wellFormed

3. Get a Work Item

Section titled “3. Get a Work Item”
Terminal window
adtk work-items get 42

Output:

ID:          42
Type:        User Story
Title:       Implement login page
State:       Active
Assigned To: jane@example.com
Priority:    2
Tags:        frontend; auth

Auto-detect from git branch

Section titled “Auto-detect from git branch”

If your branch name contains a work item ID (e.g., feature/12345-add-login), you can omit the ID:

Terminal window
# On branch feature/42-implement-login
adtk work-items get
# Automatically detects work item 42 from the branch name

3b. View Work Item Metrics

Section titled “3b. View Work Item Metrics”
Terminal window
adtk work-items metrics 42 -p MyProject

Output:

Current Status: Active
Cycle Time:     3d 4h
Lead Time:      5d 12h


  Time in Status:
    New:      1d 8h
    Active:   3d 4h


  Status Transitions:
  FROM    TO      AT
          New     2025-01-10 09:00
  New     Active  2025-01-11 17:00

4. Search with WIQL

Section titled “4. Search with WIQL”
Terminal window
adtk search wiql "SELECT [System.Id], [System.Title], [System.State] \
  FROM WorkItems \
  WHERE [System.State] = 'Active' \
  AND [System.AssignedTo] = @Me \
  ORDER BY [System.ChangedDate] DESC"

5. Search Code

Section titled “5. Search Code”
Terminal window
adtk search code "func main" -p MyProject

6. Enable Writes and Create a Work Item

Section titled “6. Enable Writes and Create a Work Item”
Terminal window
export ADTK_ENABLE_WRITES=true


adtk work-items create -p MyProject \
  --type "User Story" \
  --title "Add dark mode support" \
  --description "Implement dark mode toggle in the settings page" \
  --priority 2 \
  --tags "frontend;ux"

7. List Pull Requests

Section titled “7. List Pull Requests”
Terminal window
adtk pull-requests list myrepo -p MyProject

8. View Pipeline Runs

Section titled “8. View Pipeline Runs”
Terminal window
adtk pipelines list -p MyProject
adtk pipelines runs 42 -p MyProject

9. Check Current Sprint

Section titled “9. Check Current Sprint”
Terminal window
adtk iterations current -p MyProject

10. Get JSON Output

Section titled “10. Get JSON Output”

Every command supports --json for raw JSON output, useful for scripting:

Terminal window
adtk projects list --json | jq '.[].name'

Using as an MCP Server

Section titled “Using as an MCP Server”

stdio mode (for AI agents)

Section titled “stdio mode (for AI agents)”
Terminal window
adtk mcp

HTTP Streamable mode

Section titled “HTTP Streamable mode”
Terminal window
adtk mcp --port 8080

Example MCP Interaction

Section titled “Example MCP Interaction”

An AI agent using adtk might:

Tool: manage_work_items
Input: { "action": "get", "work_item_id": 42 }


Tool: manage_search
Input: { "action": "wiql", "query": "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'", "project_key": "MyProject" }


Tool: manage_pull_requests
Input: { "action": "list", "repo_id": "my-repo", "project_key": "MyProject", "status": "active" }

Next Steps

Section titled “Next Steps”