@thanaen/ado-cli

Lightweight CLI for Azure DevOps REST workflows (repos, branches, work items, PRs, builds).

Why this exists

This project provides a tiny scriptable command layer over the Azure DevOps API so automation agents and developers can run common actions quickly.

Requirements

• Node.js 18+ (runtime for the published npm package)
• An Azure DevOps Personal Access Token (PAT)

For development you also need Bun (used for builds, tests, and scripts).

Configuration

Set environment variables before running commands:

• DEVOPS_PAT (required)
• ADO_COLLECTION_URL (default: https://dev.azure.com/<your-org>)
• ADO_PROJECT (default: <your-project>)
• ADO_REPO (default: <your-repository>)
• ADO_INSECURE=1 (optional; only for self-signed TLS environments)

Example:

export DEVOPS_PAT="***"
export ADO_COLLECTION_URL="https://dev.azure.com/acme"
export ADO_PROJECT="MyProject"
export ADO_REPO="MyRepo"

On-prem / localserver example:

export DEVOPS_PAT="***"
export ADO_COLLECTION_URL="https://localserver/DefaultCollection"
export ADO_PROJECT="ExampleProject"
export ADO_REPO="Example Repository"
export ADO_INSECURE=1

Install

Global install (CLI available as ado):

npm i -g @thanaen/ado-cli

Usage

ado help
ado smoke

Commands

• -v, --version
• init [--local]
• config
• smoke
• repos
• branches [repo]
• workitem-get <id> [--raw] [--expand=all|fields|links|relations]
• workitems-recent [top] [--tag=<tag>] [--type=<work-item-type>] [--state=<state>]
• workitem-comments <id> [top] [--top=<n>] [--order=asc|desc]
• workitem-comment-add <id> --text="..." [--file=path]
• workitem-comment-update <id> <commentId> --text="..." [--file=path]
• prs [status] [top] [repo]
• pr-get <id> [repo]
• pr-create --title=... --source=... --target=... [--description=...] [--repo=...] [--work-items=123,456] [--tags=tag-a,tag-b]
• pr-update <id> [--title=...] [--description=...] [--repo=...] [--work-items=123,456] [--tags=tag-a,tag-b]
• pr-cherry-pick <id> --target=... [--topic=branch-name] [--repo=...]
• pr-approve <id> [repo]
• pr-autocomplete <id> [repo]
• builds [top]

Examples:

# 20 derniers bugs taggés "bot"
ado workitems-recent 20 --type=Bug --tag=bot

# Bugs "bot" encore en état New
ado workitems-recent --type=Bug --tag=bot --state=New

# Mettre à jour un commentaire existant (dédup)
ado workitem-comment-update 20485 12527 --file=./comment.md

npm publication (GitHub Actions)

The repository includes a workflow at .github/workflows/npm-publish.yml.

It can publish in two ways:

• automatically when a GitHub Release is published
• manually with Run workflow (workflow_dispatch)

Required repository secret

• NPM_TOKEN: npm automation token allowed to publish @thanaen/ado-cli

Release prep

• bump package.json version before creating the release/tag

Workflow behavior

Before publishing, the workflow runs:

• bun run fmt:check
• bun run lint
• bun run typecheck
• bun test
• npm pack --dry-run

Then it publishes with:

npm publish --access public --provenance

Agent skill included

A reusable agent skill is included at:

• skills/ado-workflows/SKILL.md

This helps AI coding agents run consistent Azure DevOps workflows using this CLI.

Development

Setup

bun install          # installs deps + sets up git hooks via lefthook

Scripts

Script	Description
bun run lint	Lint with oxlint (type-aware + type-check)
bun run lint:fix	Lint and auto-fix safe issues
bun run fmt	Format all files with oxfmt
bun run fmt:check	Check formatting without writing
bun test	Run tests
bun run typecheck	Run tsc type-check (manual, not in hooks)
bun run build	Compile to standalone binary
bun run build:dist	Build Node CLI used for npm publication
bun run prepack	Rebuild dist before npm pack/publish

Quality gates (git hooks via Lefthook)

Pre-commit — runs on staged files, auto-fixes and re-stages:

• oxfmt (format)
• oxlint --type-aware --type-check --fix (lint + fix)

Editor

Install the recommended VS Code extension (oxc.oxc-vscode) when prompted. Format-on-save and lint fix-on-save are pre-configured in .vscode/settings.json.

Security notes

• Never commit your PAT.
• Prefer setting secrets through runtime environment injection.
• ADO_INSECURE=1 should only be used in trusted internal environments.

Troubleshooting

• 400 Bad Request - Invalid URL at startup usually means one of ADO_COLLECTION_URL, ADO_PROJECT, or ADO_REPO is still using placeholder defaults.
• If strict TLS fails on internal servers, use ADO_INSECURE=1 only when appropriate for trusted self-signed endpoints.