azdo-cli

A developer-friendly CLI for triggering Azure DevOps pipelines with an interactive, guided workflow.

Built by gfean.

⚠️ Unofficial tool — not affiliated with or endorsed by Microsoft.
Uses user-provided Azure DevOps Personal Access Tokens (PATs) only.

Table of contents

• What is azdo-cli?
• Commands at a glance
• Requirements
• Installation
  • npm
  • yarn
• Quick start
  • 1️⃣ Configure credentials
  • 2️⃣ Initialize azdo-cli
  • 3️⃣ Run a pipeline interactively
• Configuration
  • Environment variables
  • azdo.config.json
• azdo login
• azdo whoami
• azdo logout
• azdo build
  • Common options
  • Examples
• azdo run
  • Options
  • Examples
• Parameter handling
• Exit codes
• Security & design principles
• Author

What is azdo-cli?

Azure DevOps pipelines are powerful, but triggering them through the web UI can be slow and repetitive.

azdo-cli lets you:

• Trigger pipelines directly from the terminal
• Select pipelines and branches interactively
• Fill in pipeline parameters with guided prompts
• Run builds without memorizing pipeline IDs
• Keep secrets local (no remote storage, no telemetry)

It’s designed to feel interactive when you want guidance, and scriptable when you don’t.

Commands at a glance

| Command | Purpose | |------|--------| | azdo login | Authenticate PAT and store credentials locally | | azdo whoami | Show the currently authenticated Azure DevOps user | | azdo logout | Remove stored PAT | | azdo init | Set up project configuration | | azdo build | Interactive, guided pipeline run | | azdo run | Trigger a specific pipeline by ID |

Rule of thumb

• Use build when you want to choose what to run
• Use run when you already know the pipeline ID

Requirements

• Node.js 18+ (uses built-in fetch)
• Git (used for branch discovery)
• Azure DevOps access
• A Personal Access Token (PAT) with permission to list and run pipelines

Installation

npm

npm install --save-dev @gfean/azdo-cli

yarn

yarn add --dev @gfean/azdo-cli

Run using:

npx azdo --help
# or
yarn azdo --help

Quick start

1️⃣ Configure credentials

npx azdo login
# or
yarn azdo login

This will:

• verify your PAT
• store it in user-level credentials
• show which user was authenticated

Then keep org/project in .env:

AZDO_ORG_URL=https://dev.azure.com/your-organization
AZDO_PROJECT=Your Project Name

2️⃣ Initialize azdo-cli

npx azdo init
# or
yarn azdo init

This will:

• Create azdo.config.json in your repo
• Discover available pipelines

3️⃣ Run a pipeline interactively

npx azdo build
# or
yarn azdo build

You’ll be guided through:

• Selecting a pipeline
• Choosing a branch
• Entering pipeline parameters
• Optionally waiting for completion

Configuration

Environment variables

| Variable | Description | | -------------- | ----------------------------- | | AZDO_ORG_URL | Azure DevOps organization URL | | AZDO_PROJECT | Exact project name |

azdo.config.json

Generated by azdo init. This file defines how azdo-cli understands your project.

Example:

{
  "orgUrl": "https://dev.azure.com/your-organization",
  "project": "Your Project Name",
  "defaults": { "branch": "develop", "pollMs": 7000 },
  "pipelines": {
    "staging_build": {
      "id": 12,
      "name": "Staging Build"
    },
    "production_build": {
      "id": 15,
      "name": "Production Build",
      "branch": "main"
    }
  }
}

Notes

• Pipeline keys are friendly aliases
• branch overrides the default branch for that pipeline
• YAML paths can be pinned if parameter discovery is needed

azdo login

Authenticate and store PAT credentials locally.

npx azdo login
npx azdo login --org-url https://dev.azure.com/your-organization

azdo whoami

Show which Azure DevOps user is currently authenticated.

npx azdo whoami

azdo logout

Remove locally stored credentials.

npx azdo logout

azdo build

Interactive pipeline runner.

Use this when you want guidance and don’t want to remember pipeline IDs.

npx azdo build

Common options

• --pipeline <id|key> – select pipeline by ID or config key
• --branch <name> – override branch
• --param <key=value> – repeatable parameter overrides
• --no-prompt – skip interactive prompts
• --no-wait – trigger and exit immediately
• --poll <ms> – polling interval

Examples

npx azdo build
npx azdo build --pipeline <pipeline_id>
npx azdo build --branch develop
npx azdo build --param releaseNotes="Release candidate build"
npx azdo build --no-prompt --branch main

azdo run

Direct pipeline trigger by ID.

Use this when:

• scripting
• automating
• running one-off builds

npx azdo run --pipeline <pipeline_id>

Options

• --pipeline <id> (required)
• --branch <name>
• --param <key=value> (repeatable)
• --no-wait
• --poll <ms>

Examples

npx azdo run --pipeline <pipeline_id>
npx azdo run --pipeline <pipeline_id> --branch main
npx azdo run --pipeline <pipeline_id> --param releaseNotes="Hotfix build"

Parameter handling

azdo-cli supports multiple ways to pass parameters:

--param key=value
--flag value
--flag=value
--no-flag

Rules:

• Flags are converted to parameters automatically

• --no-flag sets a boolean parameter to false

• Last value wins

• Values are parsed as:

  • true / false → boolean
  • numbers → number
  • everything else → string

Use quotes for values with spaces:

--releaseNotes "Initial beta release"

Exit codes

| Code | Meaning | | ---- | --------------------------------- | | 0 | Pipeline succeeded | | 1 | Error or pipeline did not succeed |

Security & design principles

• Tokens stay local
• No telemetry
• No background services
• No vendor lock-in
• Everything is transparent and inspectable

Author

Built and maintained by gfean.