microsoft/tfs-cli

README

Node CLI for Azure DevOps

NOTE: If you are looking for the new Azure DevOps CLI, see vsts-cli

This is a command-line utility for interacting with Microsoft Team Foundation Server and Azure DevOps Services (formerly VSTS). It is cross platform and supported on Windows, MacOS, and Linux.

Setup

First, download and install Node.js 4.0.x or later and npm (included with the installer)

Linux/OSX

sudo npm install -g tfx-cli

Windows

npm install -g tfx-cli

Commands

To see the list of commands:

tfx

For help with an individual command:

tfx <command> --help

Help info is dynamically generated, so it should always be the most up-to-date authority.

Command sets

tfx build (builds): Queue, view, and get details for builds.
tfx build tasks (build tasks): Create, list, upload and delete build tasks.
tfx extension (extensions): Package, manage, publish Team Foundation Server / Azure DevOps extensions.
tfx workitem (work items): Create, query and view work items.

Login

To avoid providing credentials with every command, you can login once. Currently supported credential types: Personal Access Tokens and basic authentication credentials.

NTLM support is under consideration

Warning! Using this feature will store your login credentials on disk in plain text.

To skip certificate validation connecting to on-prem Azure DevOps Server use the --skip-cert-validation parameter.

Personal access token

Start by creating a Personal Access Token and paste it into the login command.

~$ tfx login
Copyright Microsoft Corporation

> Service URL: {url}
> Personal access token: xxxxxxxxxxxx
Logged in successfully

Examples of valid URLs are:

https://marketplace.visualstudio.com
https://youraccount.visualstudio.com/DefaultCollection

Basic auth

You can also use basic authentication by passing the --auth-type basic parameter (see Configuring Basic Auth for details).

Settings cache

To avoid providing options with every command, you can save them to a settings file by adding the --save flag.

~$ tfx build list --project MyProject --definition-name println --top 5 --save

...

id              : 1
definition name : TestDefinition
requested by    : Teddy Ward
status          : NotStarted
queue time      : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time)

~$ tfx build list
Copyright Microsoft Corporation

...

id              : 1
definition name : TestDefinition
requested by    : Teddy Ward
status          : NotStarted
queue time      : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time)

If you used --save to set a default value for an option, you may need to override it by explicitly providing a different value. You can clear any saved settings by running tfx reset.

Troubleshooting & Verbose Logging

CLI Trace Output

To see detailed tracing output from the CLI, set the TFX_TRACE environment variable and then run commands. This may provide clues to the issue and can be helpful when logging an issue.

Linux/OSX:

export TFX_TRACE=1

Windows:

set TFX_TRACE=1

PowerShell:

$env:TFX_TRACE=1

Debug Output from Tests

To enable detailed debug output for all CLI commands executed during tests, set the DEBUG_CLI_OUTPUT environment variable to true:

Linux/OSX:

export DEBUG_CLI_OUTPUT=true

Windows:

set DEBUG_CLI_OUTPUT=true

PowerShell:

$env:DEBUG_CLI_OUTPUT='true'

This will print detailed command execution logs for every CLI call made by the test suite.

Mock Server Verbose Logging

To enable verbose logging for the integrated mock server (used in server integration tests), set the DEBUG_MOCKSERVER_OUTPUT environment variable to true:

Linux/OSX:

export DEBUG_MOCKSERVER_OUTPUT=true

Windows:

set DEBUG_MOCKSERVER_OUTPUT=true

PowerShell:

$env:DEBUG_MOCKSERVER_OUTPUT='true'

This will print detailed request/response and lifecycle logs from the mock server during test runs.

All three variables (TFX_TRACE, DEBUG_CLI_OUTPUT, DEBUG_MOCKSERVER_OUTPUT) are also available as pipeline variables in the Azure DevOps pipeline and default to false.

Development

Building from Source

To build the project from source:

Install dependencies:
```
npm install
```
Build the main project:
```
npm run build
```
This compiles the TypeScript source files in the app/ directory to JavaScript in the _build/ directory using the TypeScript compiler and copies necessary files.
Clean build artifacts (optional):
```
npm run clean
```

Testing

The project includes comprehensive tests, including server integration tests with an integrated mock server. To run them:

Build the project first (required):
```
npm run build
```
Run all tests:
```
npm test
```
This builds the test files and runs all test suites.

Run specific test suites:

npm run test:build-commands
npm run test:extension-commands
npm run test:commandline
npm run test:server-integration

Run tests with CI reporter:
```
npm run test:ci
```

Note: The mock server is now integrated as part of the test suite in the tests/mock-server/ directory and is automatically compiled when running tests. No separate build step is required for the mock server.

Enabling Mock Server Verbose Logging

For debugging server integration tests, you can enable verbose logging for the mock server to see detailed request/response information. This requires modifying the test files temporarily:

Locate the test file you want to debug (e.g., tests/server-integration-login.ts)

Find the createMockServer call in the before() hook:

// Current call
mockServer = await createMockServer({ port: 8084 });

// Add verbose option
mockServer = await createMockServer({ port: 8084, verbose: true });

Run the specific test to see verbose output:
```
npm run test:server-integration-login
```
Verbose output will include:
- HTTP method and path for each request
- Authorization headers (with tokens obscured for security)
- Mock server lifecycle events
- Request processing details

Example verbose output:

Mock DevOps server listening on http://localhost:8084
Mock Server: GET /_apis/connectionData - Authorization: Basic tes***ass
Mock Server: POST /_apis/build/builds - Authorization: Bearer abc***xyz
Mock DevOps server closed

Important: Remember to remove the verbose: true option before committing your changes, as it's intended for debugging purposes only.

Testing Your Changes Locally

After building, you can test your changes locally in several ways:

Using Node.js directly:

node _build/tfx-cli.js
node _build/tfx-cli.js --help

Using npm link for global installation:
```
npm link
tfx
```
To remove the link when done testing:
```
npm unlink -g tfx-cli
```

The built executable is located at _build/tfx-cli.js and serves as the main entry point for the CLI.

Contributing

We accept contributions and fixes via Pull Requests. Please read the Contributions guide for more details.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

README

Node CLI for Azure DevOps

NOTE: If you are looking for the new Azure DevOps CLI, see vsts-cli

Setup

First, download and install Node.js 4.0.x or later and npm (included with the installer)

Linux/OSX

sudo npm install -g tfx-cli

Windows

npm install -g tfx-cli

Commands

To see the list of commands:

tfx

For help with an individual command:

tfx <command> --help

Help info is dynamically generated, so it should always be the most up-to-date authority.

Command sets

tfx build (builds): Queue, view, and get details for builds.
tfx build tasks (build tasks): Create, list, upload and delete build tasks.
tfx extension (extensions): Package, manage, publish Team Foundation Server / Azure DevOps extensions.
tfx workitem (work items): Create, query and view work items.

Login

To avoid providing credentials with every command, you can login once. Currently supported credential types: Personal Access Tokens and basic authentication credentials.

NTLM support is under consideration

Warning! Using this feature will store your login credentials on disk in plain text.

To skip certificate validation connecting to on-prem Azure DevOps Server use the --skip-cert-validation parameter.

Personal access token

Start by creating a Personal Access Token and paste it into the login command.

~$ tfx login
Copyright Microsoft Corporation

> Service URL: {url}
> Personal access token: xxxxxxxxxxxx
Logged in successfully

Examples of valid URLs are:

https://marketplace.visualstudio.com
https://youraccount.visualstudio.com/DefaultCollection

Basic auth

You can also use basic authentication by passing the --auth-type basic parameter (see Configuring Basic Auth for details).

Settings cache

To avoid providing options with every command, you can save them to a settings file by adding the --save flag.

~$ tfx build list --project MyProject --definition-name println --top 5 --save

...

id              : 1
definition name : TestDefinition
requested by    : Teddy Ward
status          : NotStarted
queue time      : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time)

~$ tfx build list
Copyright Microsoft Corporation

...

id              : 1
definition name : TestDefinition
requested by    : Teddy Ward
status          : NotStarted
queue time      : Fri Aug 21 2015 15:07:49 GMT-0400 (Eastern Daylight Time)

If you used --save to set a default value for an option, you may need to override it by explicitly providing a different value. You can clear any saved settings by running tfx reset.

Troubleshooting & Verbose Logging

CLI Trace Output

To see detailed tracing output from the CLI, set the TFX_TRACE environment variable and then run commands. This may provide clues to the issue and can be helpful when logging an issue.

Linux/OSX:

export TFX_TRACE=1

Windows:

set TFX_TRACE=1

PowerShell:

$env:TFX_TRACE=1

Debug Output from Tests

To enable detailed debug output for all CLI commands executed during tests, set the DEBUG_CLI_OUTPUT environment variable to true:

Linux/OSX:

export DEBUG_CLI_OUTPUT=true

Windows:

set DEBUG_CLI_OUTPUT=true

PowerShell:

$env:DEBUG_CLI_OUTPUT='true'

This will print detailed command execution logs for every CLI call made by the test suite.

Mock Server Verbose Logging

To enable verbose logging for the integrated mock server (used in server integration tests), set the DEBUG_MOCKSERVER_OUTPUT environment variable to true:

Linux/OSX:

export DEBUG_MOCKSERVER_OUTPUT=true

Windows:

set DEBUG_MOCKSERVER_OUTPUT=true

PowerShell:

$env:DEBUG_MOCKSERVER_OUTPUT='true'

This will print detailed request/response and lifecycle logs from the mock server during test runs.

All three variables (TFX_TRACE, DEBUG_CLI_OUTPUT, DEBUG_MOCKSERVER_OUTPUT) are also available as pipeline variables in the Azure DevOps pipeline and default to false.

Development

Building from Source

To build the project from source:

Install dependencies:
```
npm install
```
Build the main project:
```
npm run build
```
This compiles the TypeScript source files in the app/ directory to JavaScript in the _build/ directory using the TypeScript compiler and copies necessary files.
Clean build artifacts (optional):
```
npm run clean
```

Testing

The project includes comprehensive tests, including server integration tests with an integrated mock server. To run them:

Build the project first (required):
```
npm run build
```
Run all tests:
```
npm test
```
This builds the test files and runs all test suites.

Run specific test suites:

npm run test:build-commands
npm run test:extension-commands
npm run test:commandline
npm run test:server-integration

Run tests with CI reporter:
```
npm run test:ci
```

Enabling Mock Server Verbose Logging

For debugging server integration tests, you can enable verbose logging for the mock server to see detailed request/response information. This requires modifying the test files temporarily:

Locate the test file you want to debug (e.g., tests/server-integration-login.ts)

Find the createMockServer call in the before() hook:

// Current call
mockServer = await createMockServer({ port: 8084 });

// Add verbose option
mockServer = await createMockServer({ port: 8084, verbose: true });

Run the specific test to see verbose output:
```
npm run test:server-integration-login
```
Verbose output will include:
- HTTP method and path for each request
- Authorization headers (with tokens obscured for security)
- Mock server lifecycle events
- Request processing details

Example verbose output:

Mock DevOps server listening on http://localhost:8084
Mock Server: GET /_apis/connectionData - Authorization: Basic tes***ass
Mock Server: POST /_apis/build/builds - Authorization: Bearer abc***xyz
Mock DevOps server closed

Important: Remember to remove the verbose: true option before committing your changes, as it's intended for debugging purposes only.

Testing Your Changes Locally

After building, you can test your changes locally in several ways:

Using Node.js directly:

node _build/tfx-cli.js
node _build/tfx-cli.js --help

Using npm link for global installation:
```
npm link
tfx
```
To remove the link when done testing:
```
npm unlink -g tfx-cli
```

The built executable is located at _build/tfx-cli.js and serves as the main entry point for the CLI.

Contributing

We accept contributions and fixes via Pull Requests. Please read the Contributions guide for more details.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.