gh-lttr-claude-marketplace-plugins-azure-devops/skills/az-cli/references/boards.md

Azure Boards CLI Reference

Work Item Queries

az boards query

Query work items using WIQL.

# Using WIQL directly
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = @project ORDER BY [System.ChangedDate] DESC"

# Common query patterns:

# My work items
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed' ORDER BY [System.ChangedDate] DESC"

# Active bugs
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'Active'"

# Items in current sprint
az boards query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.IterationPath] UNDER @CurrentIteration"

# Recently updated
az boards query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.ChangedDate] >= @Today - 7 ORDER BY [System.ChangedDate] DESC"

# Using saved query ID
az boards query --id <query-id>

# Using saved query path
az boards query --path "Shared Queries/My Query"

WIQL Field References:

• [System.Id] - Work item ID
• [System.Title] - Title
• [System.State] - State (New, Active, Closed, etc.)
• [System.AssignedTo] - Assigned user
• [System.WorkItemType] - Type (Bug, Task, User Story, etc.)
• [System.IterationPath] - Sprint/iteration
• [System.AreaPath] - Area path
• [System.Tags] - Tags
• [System.ChangedDate] - Last modified
• [System.CreatedDate] - Created date

WIQL Macros:

• @Me - Current user
• @Today - Today's date
• @CurrentIteration - Current sprint
• @project - Current project

Work Items

az boards work-item show

Show work item details.

az boards work-item show --id <work-item-id> [--open] [--expand all|relations|fields]

az boards work-item create

Create a work item.

# Basic creation
az boards work-item create --title "Task title" --type "Task"

# With description and assignment
az boards work-item create \
  --title "Fix login bug" \
  --type "Bug" \
  --description "Users cannot login with SSO" \
  --assigned-to user@email.com

# With area and iteration
az boards work-item create \
  --title "New feature" \
  --type "User Story" \
  --area "Project\\Team" \
  --iteration "Project\\Sprint 1"

# With additional fields
az boards work-item create \
  --title "Critical bug" \
  --type "Bug" \
  --fields "System.Tags=urgent;production" "Microsoft.VSTS.Common.Priority=1"

Common work item types:

• Task - Development task
• Bug - Bug/defect
• User Story - User story (Agile)
• Product Backlog Item - PBI (Scrum)
• Feature - Feature
• Epic - Epic
• Issue - Issue (Basic process)

az boards work-item update

Update a work item.

# Update state
az boards work-item update --id <id> --state "In Progress"

# Update title
az boards work-item update --id <id> --title "New title"

# Update assignment
az boards work-item update --id <id> --assigned-to user@email.com

# Update area/iteration
az boards work-item update --id <id> --area "Project\\NewArea" --iteration "Project\\Sprint 2"

# Update multiple fields
az boards work-item update --id <id> --fields "System.Tags=tag1;tag2" "Microsoft.VSTS.Common.Priority=2"

# Update description
az boards work-item update --id <id> --description "Updated description"

az boards work-item delete

Delete a work item.

az boards work-item delete --id <work-item-id> [--yes] [--destroy]

Note: --destroy permanently deletes; without it, item goes to recycle bin.

Work Item Relations

az boards work-item relation list-type

List available relation types.

az boards work-item relation list-type

Common relation types:

• System.LinkTypes.Hierarchy-Forward - Parent (child -> parent)
• System.LinkTypes.Hierarchy-Reverse - Child (parent -> child)
• System.LinkTypes.Related - Related
• System.LinkTypes.Dependency-Forward - Successor
• System.LinkTypes.Dependency-Reverse - Predecessor

az boards work-item relation add

Add a relation.

# Link to parent
az boards work-item relation add \
  --id <work-item-id> \
  --relation-type "System.LinkTypes.Hierarchy-Forward" \
  --target-id <parent-id>

# Add related item
az boards work-item relation add \
  --id <work-item-id> \
  --relation-type "System.LinkTypes.Related" \
  --target-id <related-id>

az boards work-item relation remove

Remove a relation.

az boards work-item relation remove \
  --id <work-item-id> \
  --relation-type "System.LinkTypes.Related" \
  --target-id <target-id>

az boards work-item relation show

Show work item relations.

az boards work-item relation show --id <work-item-id>

Area Paths

az boards area project list

List area paths in project.

az boards area project list [--depth <n>]

az boards area project show

Show area details.

az boards area project show --path "\\Project\\Area\\SubArea"

az boards area project create

Create an area path.

az boards area project create --name "New Area" [--path "\\Project\\ParentArea"]

az boards area project delete

Delete an area path.

az boards area project delete --path "\\Project\\Area" [--yes]

az boards area team list

List areas for a team.

az boards area team list --team "Team Name"

az boards area team add

Add area to team.

az boards area team add --team "Team Name" --path "\\Project\\Area" [--include-sub-areas true]

az boards area team remove

Remove area from team.

az boards area team remove --team "Team Name" --path "\\Project\\Area"

Iteration Paths (Sprints)

az boards iteration project list

List iterations in project.

az boards iteration project list [--depth <n>]

az boards iteration project show

Show iteration details.

az boards iteration project show --path "\\Project\\Sprint 1"

az boards iteration project create

Create an iteration.

az boards iteration project create \
  --name "Sprint 5" \
  --path "\\Project" \
  [--start-date 2024-01-15] \
  [--finish-date 2024-01-29]

az boards iteration project delete

Delete an iteration.

az boards iteration project delete --path "\\Project\\Sprint 5" [--yes]

az boards iteration team list

List team iterations.

az boards iteration team list --team "Team Name"

az boards iteration team add

Add iteration to team.

az boards iteration team add --team "Team Name" --id <iteration-id>

az boards iteration team remove

Remove iteration from team.

az boards iteration team remove --team "Team Name" --id <iteration-id>

az boards iteration team list-work-items

List work items in iteration.

az boards iteration team list-work-items --team "Team Name" --id <iteration-id>

az boards iteration team set-backlog-iteration

Set backlog iteration for team.

az boards iteration team set-backlog-iteration --team "Team Name" --id <iteration-id>

az boards iteration team set-default-iteration

Set default iteration for new work items.

az boards iteration team set-default-iteration --team "Team Name" --id <iteration-id>