Command-Line Authentication for Team Explorer Everywhere
When you perform version-control operations in Team Explorer Everywhere from a command prompt, you must authenticate yourself to the version-control server for Team Foundation. To authenticate yourself, you must specify either your domain credentials, if your organization uses Active Directory, or your workgroup credentials. By using the –login option, you can specify your credentials every time that you use any command in the tf command-line tool. If you set the TF_AUTO_SAVE_CREDENTIALS environment variable, you can also use the –login option to save your credentials in a workspace cache and update them automatically when, for example, your password changes. If you often use different sets of credentials, you can save each set in a connection profile that you specify every time you run a tf command.
For more information about the tf command-line tool, see Command-line Reference (Team Explorer Everywhere). For more information about how to set environment variables, see Set Environment Variables (Team Explorer Everywhere).
Important
For convenience, most users save their credentials to either a workspace cache or a connection profile. However, some organizations prohibit this practice for security reasons. Before you save your credentials, you should verify the relevant policy for your organization.
In this topic
The –login Option
You can use the –login option to specify your credentials if, for example, organizational policies prohibit storing that kind of information or you must override credentials that are stored in a workspace cache or a connection profile. If you use this option, you must specify your credentials in either of the following formats:
-login:domain\username,password
-login:username@domain,password
You will be prompted to specify your credentials if you have not stored them and you try to run a tf command without this option. If you try to run a tf command with this option but you do not specify a password, you will be prompted to specify one.
The following examples demonstrate how to use this option:
This example specifies the domain as “company”, the user name as “John”, and the password as “Se^%cret1”.
-login:company\john,Se^%cret1
Important
If you are using Unix shells, you need to precede the username and password with another backslash to preserve the literal value of the character. For example, -login:company\\john,Se^%cret1.
This example specifies the same credentials as the previous example in a different format.
-login:john@company,Se^%cret1
This example supplies an empty password by following the user and domain names with a comma.
-login:john@company,
This example supplies no password at all. In this case, the command-line client will prompt the user for the missing password.
-login:join@company
This example is surrounded by double quotes because the credentials contain characters that shell programs consider special. User names, domains, and passwords may require quoting or escaping to be passed correctly to the tf command-line tool. For more information, see Quoting and Escaping.
“-login:john\company, Se^%cret1”
Important
If you use the –noprompt option, you will not receive any prompt from the tf command-line tool.
Saving Credentials in Connection Profiles
If you frequently need multiple sets of credentials, you can store each set in a connection profile and then use the –profile option to specify the appropriate profile whenever you run a tf command. In each connection profile, you can store all credential information or only some of it, such as a domain name and a user name but not a password. You will then be prompted for the password whenever you run a command under that profile unless you also use the –noprompt option. If you use the –noprompt option, you can use the –login option to specify credentials for that operation only. However, you must update credentials in a connection profile manually, unlike a workspace cache. For more information, see Connection Profiles.
Saving Credentials in the Workspace Cache
If you set the TF_AUTO_SAVE_CREDENTIALS environment variable to any value and then run a tf command with the –login option, you can automatically save the credentials that you specify to the workspace cache whenever tf updates the cache. After you take these steps, you do not need to specify authentication information each time that you run a tf command. For more information about how to set environment variables, see Set Environment Variables (Team Explorer Everywhere).
Note
You can use the workspaces command to force an update to the workspace cache if you provide the command with a server URL and authentication information and the command runs successfully. However, not all commands can update the workspace cache. For more information, see Configuration and Cache Information.
The tf command-line tool can determine which cached workspace is appropriate for the command and can load the saved credentials if you do not specify the –profile option or the –login option. In addition, at least one of the following conditions must be true:
The current working directory of the tf command-line tool must be a mapped working folder.
One of the local paths that is used as a free argument to tf must be either a mapped working folder or a file inside a mapped working folder.
You must use the –workspace option to specify a workspace.
Note
Some tf commands accept the -workspace option but do not use the value of the option to find credentials. For example, the workspaces command uses the option to filter the query results.
Changing Your Username and Password
When you change your Active Directory credentials, such as username, domain name, or password, you also need to update your credentials with the tf command-line tool so that you can continue connecting to Team Foundation Server.
If you use a connection profile, update the profile’s userName, userDomain, and password properties with new values, and continue using the profile.
If you have enabled saving credential automatically in the workspace cache, provide your new credentials by using the –login option once. tf will update the saved credentials in the workspace cache.
If you do not use a connection profile and have not enabled automatic credential saving in the workspace cache, supply your new credentials with the –login option or at the interactive prompts each time when you are connecting to Team Foundation Server.