VSTS CLI

Visual Studio Team Services Command Line Interface

2017-07-12

In a previous post I did a brief tour of parsing command line arguments for your .NET console applications using the new CommandLineUtils package from Microsoft.

As a command line junkie of sorts and a big fan of the Hub project from GitHub I was looking for a quick way to status information from my current VSTS projects. Things like CICD pipeline status as well as seeing work items assigned to me. The VSTS portal isn't too bad of an implementation but there is a lot of clicking required to get around to various screens to get information. I set out to make a simple utility that works for my 75% of the tasks that I use on a daily basis.

VSTS-CLI

Silvrback blog image sb_float_center

You can find the vsts-cli over at GitHub. I'll wait here while you scratch you head over that one but honestly while you can run free projects with VSTS they still have to be projects with selecting templates and getting work items and there are build and release definitions and really ... ... I just wanted a repo with some "things" to track against it. GitHub is a better use-case for this.

The VSTS-CLI is a simple command invoked as vsts that allows you (read-as: me) to work with the common tasks that you would be using the VSTS portal for.

Getting Started

An upfront concept with the vsts-cli is registering a current working git directory with a VSTS project you have access too. This is kept in a vsts-cli file within a .config directory. Guess who else keeps their config there? Sup Hub - "oh you're here too, that's cool!"

At the top of the config if some identity stuff, Name as it sits in VSTS, the account name which is the hostname part of your VSTS url and a personal access token which is use to authorize all the API call the tool makes on your behalf to VSTS.

Under the User Section is where the projects are listed and under each project are the repos so you end up with

Account1
Eric Williams
SomeWorkAccount.visualstudio.com
PAT (Personal Access Token)
- Project 1
  - Repository A
  - Repository B
- Project 2
  - Repository A
  - Repository B
Account2
Eric Williams
SomeOtherWorkAccount.visualstudio.com
PAT (Personal Access Token)
- Project 1
  - Repository A
- Project 2
  - Repository A
- Project 3
  - Repository A

First Run

If you run vsts in a directory or parent that doesn't have a git repo it will no-op with a

C:\Users\eric\code\ewilliams-vsts
»  vsts
Could not find an existing VSTS git repo in the current C:\Users\eric\code\ewilliams-vsts directory or parent directories

which makes since since it is a repo first based utility. Go clone a VSTS repo and cd to that location.

If you run vsts in a directory where that has a git repo but you've never setup a PAT (personal access token) it will prompt you for that and save it to the configuration file.

C:\Users\eric\code\ewilliams-vsts\TestProject1 [master ≡]
»  vsts
Please enter name as recorded in your VSTS account: Eric Williams
Please enter your personal access token: ****************************************************

aftwards you get a little json in your config file like

[
  {
    "FullName": "Eric Williams",
    "AccountName": "your_vsts_instance_host_name",
    "PersonalAccessToken": "that_token",
    "Projects": [
      {
        "Id": "some_project_guid",
        "Name": "TestProject",
        "Repositories": [
          {
            "Name": "TestProject1",
            "Id": "some_repo_guid",
            "Directory": "C:\\Users\\eric\\code\\ewilliams-vsts\\TestProject1\\.git"
          }
        ]
      }
    ]
  }
]

You'll notice that there is more information here that you entered yourself. The vsts-cli looked at your git repo configruation by using the awesome project libgit2sharp and grabbed the host name of your origin url saving that as the Account Name. Next it made an API call to get a collection of repos in your VSTS project and found a match to the one in your current directory. It looked at that repos parent project for the project Name and Id. It also grabbed the current repo's official Name and Id.

If you git clone another repo in your project it will slip stream that entry into the configuration before finishing the work you requested.

[
  {
    "FullName": "Eric Williams",
    "AccountName": "your_vsts_instance_host_name",
    "PersonalAccessToken": "that_token",
    "Projects": [
      {
        "Id": "some_project_guid",
        "Name": "TestProject",
        "Repositories": [
          {
            "Name": "TestProject1",
            "Id": "some_repo_guid",
            "Directory": "C:\\Users\\eric\\code\\ewilliams-vsts\\TestProject1\\.git"
          },
          {
            "Name": "TestProject2",
            "Id": "some_repo_guid",
            "Directory": "C:\\Users\\eric\\code\\ewilliams-vsts\\TestProject2\\.git"
          }
        ]
      }
    ]
  }
]

At this point you are ready to fire off some of those "used daily" commands!

Build Information

There are commands to view all the builds for all the repos in a project (remember a VSTS project can have multiple repos). This will spit out traffic signal style color coding for broken builds, successful build and and builds currently running.

Silvrback blog image sb_float_center

You can get details of the individual build steps for a given build to see what part is broken.

Silvrback blog image sb_float_center

You can also get the entire build log and view it directly in your command prompt for when you want to quickly scan for issues.

Silvrback blog image sb_float_center

Work Items

The work items command will get you query and create work items for a project.

To see all the non-closed work items in a project issue a vsts wi

»  vsts wi
#18 New    Epic       2017/07/12 unassigned    Super Epic : no tags
#19 Active Feature    2017/07/12 Eric Williams Super Feature : no tags
#20 New    User Story 2017/07/12 unassigned    Super Story : no tags

Or you can supply various argumnets to get different queries in your console

»  vsts wi -s closed
#21 Closed User Story 2017/07/12 unassigned Less Than Super Story : no tags

Or maybe see the description on the card?

»  vsts wi -s closed -d
#21 Closed User Story 2017/07/12 unassigned Less Than Super Story : no tags
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

You can also quickly add a work items too

»  vsts wi add -w bug -t "Console main doesn't support async"
#22 New 2017/07/12 - Console main doesn't support async

And to see that bug

»  vsts wi bug
#22 New Bug 2017/07/12 unassigned Console main doesn't support async : no tags

I mean in the portal

»  vsts wi 22 -b

launches your default browser to https://your-account.visualstudio.com/your-project/_workitems?id=your-work-item-id

Silvrback blog image sb_float_center

Pull Requests

This area still needs a little more attention as for now you can only view and create.

Assuming you've already pushed a topic branch and commit some awesome features to it then you can issue a

»  vsts pr create -t "Updates the readme" -d "This adds a link to the readme"
Create New Pull Request
-----------------------
Title: Updates the readme
From: feature/updates-readme
To: master
Description: This adds a link to the readme
Submit this pull request y/[n]

This aborts the pull request since y or yes wasn't supplied. Whereas the following will go ahead and submit the request and display it afterwards

»  vsts pr create -t "Updates the readme" -d "This adds a link to the readme"
Create New Pull Request
-----------------------
Title: Updates the readme
From: feature/updates-readme
To: master
Description: This adds a link to the readme
Submit this pull request y/[n] y
#1 Updates the readme by Eric Williams

The only subtle difference you see here is that it will show the PR summary.

To see the open PRs it is simply

»  vsts pr
#1 Updates the readme by Eric Williams

and if you want to view it in the portal

»  vsts pr 1

will take you too

Silvrback blog image sb_float_center

What else is there?

Some of less interesting features are the browser launchers.

»  vsts browse

Depending on the options supplied it will take you to the various sub-dashboards for builds, releases, workitems, pullrequests or testmanagement. The Wiki needs to be added and if you call vsts code it will take you to the online code browser for the current branch.

What is missing

The big one is releases. I haven't even looked at those APIs yet. Another one is queuing a build which is another common thing that I use but just haven't gotten around to putting that into vsts-cli yet.

I have a few unit tests in place and have no problem accepting issues and collaborating on some pull requests. There is an AppVeyor build in place just to keep my honest and a simple build script for local development. My current workflow is just to have the build artifacts directory in my path and when I find issues I try to get those fixed after hours and just build/use it from that location. Crude but it works for now as it is very 'work in progress' Another thing I'd like to do is get it compiled down to a single exe or maybe try to figure out the .NET Native or CoreClr or whatever is called so that I can have it available for Linux and OSX folks.

All in all it is a tool that saves me some time during the day when interacting with VSTS. If you're interesting head over to my GitHub repo and take a look - vsts-cli