Get started with the VSTS CLI

VSTS CLI is Visual Studio Team Services (VSTS) new command line experience for managing VSTS resources. You can install it on macOS, Linux, and Windows and run it from the command line.

VSTS CLI is optimized for managing and administering VSTS resources from the command line, and for building automation scripts that work against your VSTS or Team Foundation Server account. This article helps get you started using it, and teaches you the core concepts behind it.

VSTS CLI is supported on Team Foundation Server 2017 update 2 and later. For information about the latest release, see the release notes.

Note

Before getting started with this article, learn how to install the CLI here if you haven't already.

Set up credentials and connect to VSTS

First, create a personal access token if you don't have one.

To make full use of the VSTS CLI, you should check the All scopes option when creating the token. If you only need to interact with a specific VSTS account, limit your token to just this account.

Before you can run VSTS commands, you need to run the vsts login command to sign in or set up credentials. Running vsts login securely stores your PAT and establishes default credentials:

vsts login --token xxxxxxxxxx 

Replace xxxxxxxxxx with the PAT you created.

Create a pull request

Within your src folder, run the vsts code pr create command to create a pull request.

vsts code pr create --target-branch {branch_name}

Create a work item

You can create work items, like bugs, with the vsts work item create command.

vsts work item create --type bug --title "Typo in docs"

Listing resources and formatting output

You can use the list command within the VSTS CLI to find and list the resources running in VSTS.

Like with the create command, you can list resources using the VSTS CLI using a common vsts <resource type name> list naming pattern that is consistent across all resource types. There are various output formats available to filter and sort the list of resources in the way you prefer to see them.

For example, vsts code pr list shows the list of all pull requests you have.

vsts code pr list

The values returned in JSON by default (only showing partial output for sake of brevity).

[
{
    "artifactId": null,
    "autoCompleteSetBy": null,
    "closedBy": null,
    "closedDate": null,
    "codeReviewId": 1,
    "commits": null,
    "completionOptions": null,
    "completionQueueTime": null,
    "createdBy": {
      "directoryAlias": null,
      "displayName": "Fabrikam Fiber",
      "id": "1234fab1-1234-1234-1234-fabrikam1234",
      "imageUrl": "https://fabrikam-fiber-cli.visualstudio.com/_api/_common/identityImage?id=1234fab1-1234-1234-1234-fabrikam1234",
      "inactive": null,
      "isAadIdentity": null,
      "isContainer": null,
      "profileUrl": null,
      "uniqueName": "fabrikam@contoso.com"
      }
]

You can optionally modify the output format using the --output option. Run the vsts code pr list --output table command to see the pull request we created earlier, using the easy to read table format option:

table

ID      Created     Creator                 Title                    Status     Repository
------  ----------  ----------------------  -----------------------  --------  --------------------
270621  2017-10-19  fabrikam@contoso.com     fabrikam/update-repo    Active     Demos

tsv

The tsv output option can be used to get a text-based, tab-separated format without any headers. This format is useful when you want to pipe the output into another text-based tool like grep.

vsts code pr list --output tsv
None    None    None    None    1       None    None    None            2017-10-30T18:50:18.086685+00:00        None    None    None                            None    None    859b58ee-0e90-4a06-acce-e199823741b6 None    succeeded       1       None            2       refs/heads/fabrikam/update-repo   active  True    refs/heads/master       Merge fabrikam/update-repo to master      https://fabrikam-fiber-cli.visualstudio.com/_apis/git/repositories/b2cfc2a9-499f-41af-b2ae-f4aedade5e9e/pullRequests/1   None

Note

Visit the output formats article to learn more about the additional ways to list resources and format the output.

Log out and clear credentials

You can clear credentials by running the vsts logout command:

This will log you out and require you to use a PAT again to log back in.

vsts logout

Get help

The VSTS CLI has built-in help documentation that you can access from the command line:

vsts [command-group [command]] -h

For example, to see what commands and subgroups are available for code, use:

vsts code -h

To get help with the command to create a pull request, use:

vsts code pr -h

Send us your feedback

You can also send feedback directly from the command line tool with the vsts feedback command:

vsts feedback