@semeton/azure-boards-cli (azb)

A lightweight Node.js CLI for managing Azure Boards work items from the terminal. Built to work standalone across any project, and with first-class integration for the @semeton/agent-contract agentic coding workflow.

Quick start

# 1. Install
npm install -g @semeton/azure-boards-cli

# 2. Interactive setup — fetches your real orgs, projects and teams
azb init

# 3. List your active tickets
azb list

# 4. View a ticket
azb view 1234

# 5. Update state
azb state 1234 "Active"

For detailed setup options see INSTALLATION.md.

Commands

| Command | Description | |---|---| | azb init | Interactive setup — fetches orgs, projects, teams live from Azure DevOps | | azb auth <token> | Save a PAT directly (then run azb init to pick org/project) | | azb list | My active work items | | azb list --status "Active" | Filter by state (comma-separated) | | azb list --all | Show all assignees | | azb list --closed | Include closed/resolved | | azb view <id> | Full detail for a work item | | azb view <id> --context | Plain-text output (for AI context) | | azb state <id> <state> | Update work item state | | azb comment <id> <text> | Add a comment | | azb open <id> | Open in browser | | azb sprint | Current sprint board |

Common states

New  →  Active  →  Resolved  →  Closed

Configuration

Auth is resolved in this order:

1. AZURE_DEVOPS_PAT environment variable
2. ~/.azb/config.json (written by azb init)

Run azb init for interactive setup — it fetches your real orgs, projects and teams from Azure DevOps so you never type names manually. The config is stored at ~/.azb/config.json:

{
  "pat": "your-token",
  "org": "your-org",
  "project": "Your Project",
  "team": "Your Project Team"
}

Claude Code skill

Once installed, type /azb <ticket-id> in any Claude Code session to pull the ticket's title, description, and acceptance criteria directly into context — no copy-pasting.

/azb 1234        → fetches ticket #1234
/azb sprint      → shows current sprint
/azb list        → shows your active items

See docs/agent-contract.md for the full agentic workflow integration.

Project structure

azure-boards-cli/
├── bin/
│   └── azb.js              # CLI entry point
├── commands/
│   ├── list.js
│   ├── view.js
│   ├── update.js
│   ├── open.js
│   └── sprint.js
├── lib/
│   ├── api.js              # Azure DevOps REST client
│   ├── config.js           # Auth + config loading
│   └── format.js           # Terminal output formatting
└── docs/
    └── agent-contract.md   # Agent-contract integration guide

Requirements

• Node.js 18+
• An Azure DevOps Personal Access Token with Work Items (Read & Write) scope

Docs

• INSTALLATION.md — setup for new developers
• CONTRIBUTING.md — adding commands and sending PRs
• docs/agent-contract.md — agentic workflow integration