Azure Boards CLI Reference

Required Rules

• Use the project name defined in AGENTS.md for all Azure Boards commands and paths.
• If the project name is missing in AGENTS.md, ask the user explicitly and do not assume a project name.
• For "assigned to me" lookups or assigning tickets to the user, use the value from AZURE_DEVOPS_USERNAME.
• When creating new tickets, always assign them to the latest iteration by default.
• Only use a non-latest iteration when the user explicitly asks for a different one.

Configuration

Required environment variable:

• AZURE_DEVOPS_USERNAME — used for "assigned to me" lookups and assignments to the current user.

Rules:

• Assume az CLI and azure-devops extension are already installed and authenticated.
• Assume Azure DevOps defaults (organization, project) are already configured in the environment.
• If defaults are missing at runtime, ask the user for the missing value(s) and continue with explicit --org / --project flags.

Execution Model

Use Azure CLI commands via az boards.

Create Work Item

az boards work-item create \
  --type "Task" \
  --title "My Task" \
  --description "<p>HTML description here</p>" \
  --assigned-to "user@example.com" \
  --fields "System.IterationPath=Project\\Sprint 1" "Microsoft.VSTS.Scheduling.OriginalEstimate=2" \
  --tags "frontend;urgent"

Key Arguments

Common Fields (--fields)

Update Work Item

az boards work-item update \
  --id 12345 \
  --state "Active" \
  --assigned-to "user@example.com" \
  --fields "Microsoft.VSTS.Scheduling.RemainingWork=2"

All arguments are optional except --id. Only provided fields are updated.

Get / Show Work Item

az boards work-item show --id 12345

Returns work item JSON including core fields and links.

Delete Work Item

# Soft delete (recycle bin)
az boards work-item delete --id 12345 --yes

# Permanent delete
az boards work-item delete --id 12345 --yes --destroy

Query Work Items (WIQL)

az boards query \
  --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.IterationPath] = 'Project\Sprint 1' AND [System.WorkItemType] = 'Task'" \
  --top 50 \
  --output json

If you need full details for each result, fetch each returned ID with az boards work-item show --id <id>.

az boards query \
  --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.AssignedTo] = 'Kamaljot Singh' AND [System.State] = 'Active'" \
  --output json

Link Work Items (Relations)

az boards work-item relation add \
  --id 100 \
  --relation-type Parent \
  --target-id 200

Relation Types

Remove a relation by relation ID:

az boards work-item relation remove \
  --id 100 \
  --relation-id 300

Comments (Discussion)

# Add a comment
az boards work-item update \
  --id 12345 \
  --discussion "<p>Investigation complete — root cause is X.</p>"

Iteration / Sprint Management

# List all iterations
az boards iteration project list

# Filter by timeframe
az boards iteration team list --timeframe current

# Show the current (or latest) iteration
az boards iteration team list --timeframe current --output table

Typical Workflow: Create Task Under User Story

Two-step workflow with direct CLI:

az boards work-item create \
  --type "Task" \
  --title "Implement feature X" \
  --description "<p>Details here</p>" \
  --assigned-to "user@example.com" \
  --fields "Microsoft.VSTS.Scheduling.OriginalEstimate=4"

az boards work-item relation add \
  --id <new-task-id> \
  --relation-type Parent \
  --target-id 5678

CRITICAL: Description and comment fields require HTML, NOT markdown

The --description and --discussion (comment) fields are rendered by Azure DevOps as HTML. If you pass raw markdown, it displays as literal plain text.

Always use HTML tags:

<h2>Summary</h2>
<p>Explanation with <code>inline code</code> and <b>bold</b>.</p>

<h2>Steps to reproduce</h2>
<ol>
  <li>First step.</li>
  <li>Second step.</li>
</ol>

<h2>Acceptance criteria</h2>
<ul>
  <li>Endpoint returns <b>200</b> for valid input.</li>
</ul>

Quick mapping:

Do NOT:

• Pass raw markdown to --description — it will render as a single blob of text.
• Repeat the work item title inside Description (it's already in System.Title).
• Add a **Description:** label inside the Description field (it's redundant).

Gotchas

• Description is HTML, not markdown — see section above. This is the #1 mistake.
• Parent link is a separate step — create the work item first, then link parent/child with relation add.
• Set iteration explicitly when creating — use System.IterationPath in --fields (latest/current iteration by default unless user asks otherwise).
• Estimate fields are in hours — 0.5 = 30 minutes, 8 = one day.
• Work item types are case-sensitive — "User Story" not "user story".
• --fields uses full API field names — find them via show on an existing item.
• Sprint board visibility — tickets won't appear on a sprint taskboard if unassigned and the board is filtered by person. Always set --assigned-to.