ado Azure DevOps CLI

The Azure DevOps CLI
for humans and LLM agents

Structured --json output on every command. Embedded skills for pi, Claude Code, Cursor, Codex, and GitHub Copilot. Single self-contained binary for macOS, Linux, and Windows.

npm recommended 
npm install -g @gilbertwong1996/ado --foreground-scripts

Works on macOS, Linux, and Windows. Other install methods →

CI Elixir 1.20+ Apache-2.0

What it does

24 service areas

Projects, repos, work items, pipelines, builds, pull requests, packages, security, agent pools, branches, wikis, service connections, and more.

3 auth methods

Personal Access Token, browser OAuth (PKCE), device code. MSA personal accounts (*.visualstudio.com) supported. No az CLI dependency.

Cross-platform

One self-contained binary for macOS (arm64/x86_64), Linux (x86_64/aarch64), and Windows x86_64. Built with Burrito.

CI/CD friendly

ado ci watch PROJECT BUILD_ID streams build logs in real time. Per-run variables, variable groups, PR automation, package publishing.

Why "AI-native"?

Most CLIs are designed for humans and retrofitted for AI agents with --json flags that nobody uses. ado is designed the other way around.

Feature Human-friendly AI-agent-friendly
Output Tables + colors Stable JSON envelopes on every command
Discovery ado --help → 3 levels deep ado schema --json — full command tree in 1 round trip
Documentation Embedded help pages ado skills list / ado skills read NAME --json
Errors Pretty stack traces {ok: false, error: {code, status, message, details}}
Auth Browser OAuth (interactive) PAT, device code, browser — all machine-discoverable
Distribution npm install -g ado (or download binary) Single self-contained binary, no runtime deps

Try it: structured output in one command

$ ado projects list --json
{
  "ok": true,
  "count": 3,
  "items": [
    { "id": "...", "name": "alpha", "state": "wellFormed" },
    { "id": "...", "name": "beta",  "state": "wellFormed" },
    { "id": "...", "name": "gamma", "state": "deleting"  }
  ]
}

Errors that agents can match on

$ ado projects show nonexistent --json
{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Resource not found. Check the project/repo/build ID and your permissions.",
    "status": 404,
    "details": { "body": "..." }
  }
}

Every error has a stable code from a small set: auth_required, not_found, forbidden, conflict, validation_error, api_error, network_error, cancelled. LLM agents match on error.code, not on English text.

For LLM agents

The CLI ships with 3 embedded skills that teach agents how to use it. Install them once and the agent loads them natively on startup — no shell-out overhead. 

$ ado skills install

  Installing 3 skills to 4 target(s):
    - pi:     ~/.pi/agent/skills
    - claude: ~/.claude/skills
    - cursor: ~/.cursor/skills
    - codex:  ~/.codex/skills

  Installed: 12
  Skipped:   0
  Errors:    0

$ ls ~/.pi/agent/skills
ado-cli/  ado-auth/  ado-ci/

What the skills teach

ado-cli

Complete command reference for all 24 service areas. The big one — load it when the agent first encounters ado.

ado-auth

How to authenticate: PAT, browser OAuth, device code. Covers headless/CI flows. No az dependency.

ado-ci

CI/CD patterns: trigger pipelines, manage variable groups, automate PRs, publish packages.

Or — discover dynamically

Agents that don't install skills can still discover the full surface in one call:

$ ado schema --json | jq '.schema.subcommands | length'
28

$ ado schema ci watch --json | jq '.schema.options[].name'
"project"
"build_id"
"poll_interval"
"json"

Other install methods

Prefer a single binary over npm? Download the one that matches your platform from the latest release, or build from source.

📥 Download binary

Grab the platform-specific binary and put it on your $PATH.

curl -L -o ado https://github.com/gilbertwong96/ado_cli/releases/latest/download/ado-0.4.12-macos-aarch64
chmod +x ado && sudo mv ado /usr/local/bin/

Replace ado-0.4.12-macos-aarch64 with the binary for your platform (see the release page).

🔨 Build from source

Requires Elixir 1.20+ and Mix. Use this if you want to hack on ado itself.

git clone https://github.com/gilbertwong96/ado_cli && cd ado_cli
mix deps.get && mix escript.build
cp ado /usr/local/bin/

Quick start

# 1. Authenticate (pick one)
ado login                                         # browser OAuth (org auto-detected)
ado login --method pat --org myorg --pat TOKEN   # Personal Access Token
ado login --method device                         # no browser needed

# 2. List projects
ado projects list

# 3. Get machine-readable output for an LLM agent
ado projects list --json | jq '.items | length'

# 4. Create a work item
ado workitems create MyProject --type Bug --title "Fix login page"

# 5. Watch a pipeline run in real time
ado ci watch MyProject 12345

# 6. Install skills to your LLM agent
ado skills install --target pi