# ado

> ado is a single-binary Azure DevOps CLI written in Rust. It covers 150 commands across 24 Azure DevOps service areas with the command vocabulary of `gh` (singular nouns, `view`/`edit`/`merge`/`close`), field-selected JSON, in-process `jq` and Go templates, tab-separated output when piped, and stable process exit codes. Version 0.7.0, Apache-2.0, macOS/Linux/Windows, no runtime dependency.

## Facts

- Binary: one self-contained file of about 5 MiB; no Python, Node or `az` CLI required.
- Startup: about 6 ms to first output.
- Command shape: `ado <noun> <verb>`, one level deep — `ado pr list`, `ado pr view`, `ado pr edit`, `ado work-item create`, `ado pr-comment add`.
- Output: a stable envelope, `{"ok": true, ...}` or `{"ok": false, "error": {"code", "status", "message", "details"}}`, on every command under `--json`.
- Field selection: `--json=number,title` prints only those fields, in `gh`'s vocabulary where it maps.
- Post-processing: `-q/--jq EXPRESSION` and `-t/--template TEMPLATE` are compiled into the binary; neither tool needs to be installed.
- Piped output: tables become tab-separated rows with no header, so `cut -f2` addresses a column.
- Exit codes: 0 success, 1 failure, 2 a cancelled `ado ci watch`, 4 no credential (`not_logged_in`).
- Error codes: `auth_required`, `not_logged_in`, `not_found`, `forbidden`, `conflict`, `validation_error`, `api_error`, `network_error`, `cancelled`, `unknown`.
- Repository targeting: `-R PROJECT/REPO`, or nothing at all inside an Azure DevOps checkout, where the pair is read from `git remote get-url origin`.
- Web pages: `-w/--web` opens the page a command is about, built from the host and organization `whoami` reports; no request is made, so no credential is needed.
- Search: `ado search work-item|code|wiki QUERY` asks the organization's Search host, which is project-scoped, so the project is a flag.
- Defaults: `ado config list|get|set` reads and writes `default_org` and `server` in the config file; credentials stay in the OS store, never in that file.
- Escape hatch: `ado api PATH` sends one authenticated request to any endpoint and exits with the server's status.
- Auth: Personal Access Token, browser OAuth (PKCE), device code. `ado auth token` prints the stored credential for `git` or `curl`.
- Agents: the binary embeds three skills (`ado-cli`, `ado-auth`, `ado-ci`); `ado skills install` writes them to pi, Claude Code, Cursor, Codex or GitHub Copilot. `ado schema --json` dumps the whole command tree in one call.

## Install

- [npm](https://www.npmjs.com/package/@gilbertwong1996/ado): `npm install -g @gilbertwong1996/ado --foreground-scripts`
- [Release archives](https://github.com/gilbertwong96/ado_cli/releases/latest): five native targets.

## ado compared with the official az devops CLI

Both talk to the same REST API and solve different problems.

- ado suits scripts and LLM agents: one 5 MiB binary, about 6 ms startup, gh-shaped commands, field-selected JSON with built-in `jq`, TSV when piped, stable error codes and exit 4 for a missing credential, plus `ado api` for endpoints it does not model.
- az devops suits breadth and support: Microsoft-supported, complete Azure DevOps and Azure coverage, service-principal and managed-identity sign-in, and an extension ecosystem. ado offers none of those.
- ado does not read or write az credentials, so both can be installed on one machine.

## Links

- [Landing page](https://gilbertwong96.github.io/ado_cli/)
- [Repository](https://github.com/gilbertwong96/ado_cli)
- [README](https://github.com/gilbertwong96/ado_cli#readme)
- [Usage guide](https://github.com/gilbertwong96/ado_cli/blob/main/USAGE.md)
- [Authentication guide](https://github.com/gilbertwong96/ado_cli/blob/main/AUTH.md)
- [Changelog](https://github.com/gilbertwong96/ado_cli/blob/main/CHANGELOG.md)
- [Releases](https://github.com/gilbertwong96/ado_cli/releases)