JST.AzureDevopsCli
1.0.4
See the version list below for details.
dotnet tool install --global JST.AzureDevopsCli --version 1.0.4
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local JST.AzureDevopsCli --version 1.0.4
#tool dotnet:?package=JST.AzureDevopsCli&version=1.0.4
nuke :add-package JST.AzureDevopsCli --version 1.0.4
Azure DevOps CLI
A simple, no-frills CLI tool for interacting with the Azure DevOps APi
NOTE: This tool is still a work in progress, and syntax and parameters may change without warning
Installation
This is a dotnet tool, so to install simply run dotnet tool install -g JST.AzureDevOpsCLI
. If you already have the tool installed, you can update it by running dotnet tool update -g JST.AzureDevOpsCLI
.
After installation, you can invoke the tool by running ado
in your terminal.
Auto-resolution
The tool will attempt to resolve the Azure DevOps organization and project. It does this by finding the first remote of the current git repository that matches the expected pattern. If you for some reason which to override this,
or use the tool outside of a git repository, both values may be supplied manually: ado GetBuilds organization=MyOrg project=MyProject
Getting started
In order to use this application, you must login. This application uses PAT-based authentication, which you can generate via Azure DevOps. You may give the PAT whichever scope you wish, as long as you cover your intended use cases.
NOTE: This tool will store the PAT base64 encoded in SpecialFolder.ApplicationData
Next step is to invoke the login command, which may be done in one of two ways:
"mypat" | ado login
ado login "mypat"
The first variant may be desirable if you wish to avoid having the PAT in your command history. You can paste the PAT into a file and then pipe the contents of the file to the login command.
NOTE: PATs are stored per organization and you may only one per organization
NOTE: The login command does not validate the PAT
Special commands
The default behavior of the tool is to attempt to map whichever command you've specified to a known API method, but there are exceptions:
list-areas
- Lists all known areas. Areas are method groups, like Build, Release, Approval, etc. For the most part, which area a command exists under is not going to be relevant.
list-commands (area)
- Lists all known commands. If area is specified, the list is limited to the commands of the given area
search-command <term>
- Lists all commands that match the given term. The search is case-insensitive and only a partial match is necessary
show-command <name> (area=<area>)
- Shows detailed information about the given command. Optionally, the area
parameter may be supplied to limit the output
auto-detect
- Runs the Azure DevOps organization and project auto-detection method in the current path and outputs the result
Invoking an API call
Each API method has three things that makes them unique, name, area and HTTP method. Unless you're trying to invoke an API method with a non-unique name, you don't have to supply either area or HTTP method.
API methods have a set of parameters, which can be any combination of route, query, body, or headers. Regardless of position in the call, all parameters are defined in the same waay:
name = value
(the whitespaces surrounding =
are optional)
As an example, fetching revision 1 of the build definition 123 would look like this:
ado GetDefinition definitionId=123 revision=1
Some methods require a body to be sent with the request, which may be supplied in one of two ways:
"myBody" | dotnet ado ...
ado ... body="myBody"
Flags
There are a number of flags that, when set, will affect the output of an API call. These flags are only valid when invoking an API call.
-s
or --silent
- Suppress all output
-p
or --pretty
- Pretty-print (format) the output
--what-if
- Instead of invoking the command, show the full URL that would have been invoked and, if supplied, the body as well.
Query
Finally, there is a special flag: query
. Using the JUST.net's transformer, the result of the call will be transformed by the specified query, wrapped inside #valueof.
I.e., given the query "foo"
, the transformer will receive "\"#valueof(foo)\""
and the output will replace the original output. The output is currently not pretty-printed, but this will change with a future release.
To extract the id of each build, you could use the following query: ado GetBuilds --query="value[*].id"
Roadmap
This is a first release of the tool, and some features are missing or incomplete. This is a non-exhaustive list of things that need to be addressed:
- Verify that the body is valid JSON (when expected)
- Generate DTOs for each body type, for easier validation
- Look at the content-type header to decide how to treat the response
- Improve error messages
- Improve
show-command
output - Validate input against enum-values
- Validate input against expected type
- If a parameter is specified more than once, group the values together in a comma-separated list
Release the source codeAdd support for header parameters
Notes on changes
- You are no longer required to prefix a parameter with ':' when invoking a command
- To run a query on the result, use the
--query
(or-q
) flag instead of thequery
parameter
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.
This is the first release of the tool, it is still a work in progress and there will be bugs