Scripting in the Cross-platform Command-line Client for Team Foundation Server

You can automate tasks such as compiling, packaging, or archiving source code by scripting the tf command-line tool in Team Explorer Everywhere. You can use either external or internal automation, depending on which method best suits your needs.

To use external automation, you configure another process to invoke the tf command-line tool repeatedly with fully contextual arguments each time. You do not need any special syntax to enable this mode. You can use one of the following external processes to implement this method:

  • a Unix shell, such as sh, ksh, bash, or csh

  • Perl or another programming language that is used for scripting

  • Apache Ant or another build-oriented tool

  • Any other tool that can start the tf program and supply arguments

External automation has the following advantages:

  • It is more flexible than internal automation, which can run only the tf commands. If your automation work requires running other commands, you may need to split your command file into multiple files or use external automation.

  • It is simple. If you are familiar with the external process or language, you invoke the tf command-line tool the same way as any other command-line process.

  • It is easy to debug. If some commands do not run as you expect, you do not need to change the commands at the command-line for diagnosing problems.

The external method has the following disadvantages:

  • It is slower than internal automation. For each command that you run, the CPU must spend time starting the Java virtual machine and preparing to run the client.

  • The external process must detect errors. If the external process does not test the exit code of each execution, the process may miss an error.

  • It can be more cumbersome to program. The external process must supply all relevant options each time that it runs the tf command-line tool, and the arguments may require special quoting or escaping.

To use internal automation, you configure the tf command-line tool to drive the automation process and interpret a command file that is passed as an argument. You can invoke internal automation by supplying the @ symbol immediately followed by a local path to a command file. Any additional arguments that you supply in this command line are available to commands in the command file as positional arguments.


To process standard input as your command file, supply the @ symbol with no file name following it (tf@). The input stream is interpreted as text according to your platform's default encoding and character set.

The internal method has the following advantages:

  • It is faster than the external method. Because the Java virtual machine is loaded only once and the command-line tool can re-use its connections to the server, you can execute multiple commands in a command file more quickly than if you run each command separately.

The main disadvantage of the internal method is the loss of flexibility in the following ways:

  • You can specify only tf commands in the command file, so you may need to write multiple command files and run each of them if you want to perform other tasks between tf commands.

  • Execution stops at the first error condition that you encounter. You cannot force the tool to skip or ignore any error condition.

  • You might find that deal with normal or error output is more complicated. A process that is running the tool with internal automation may not be able to determine which line in the command file produced which part of the normal output.

The following command file gets the specified version of a file and prints detailed historical information about that version.

# This line is ignored because it is a comment.
get "-version:%2" -force "%1"
history -format:detailed "-version:%2" "%1"

The command file, which is named /home/john/get-and-history.tfc, expects two positional arguments, so you can run it as the following example shows:

tf @/home/john/get-and-history.tfc README.doc C5087

The first argument, README.doc, is substituted for %1 when each line is interpreted. C5087 is substituted for %2.


In the command file, both positional arguments are surrounded by double quotation marks because their substituted values may contain spaces (for example, a file name or a date version specification).

The format of the command file can be described by the Extended Backus-Naur Form (EBNF):

command file ::= { line } ;
line ::= comment line | blank line | action line , EOL ;
comment-line ::= "#" | "rem" , { ? any non-EOL character ? } ;
blank line ::= { ? any whitespace character ? };
action line ::= tf command , [ { white space , tf option } ] , [ { white space , tf free argument } ] ;
tf command ::= ? any tf command ?
tf option ::= ? any tf option ? | positional argument ;
tf free argument::= ? any tf free argument ? | positional argument ;
positional argument::= "%" , non-zero digit , [ { digit } ] ;
EOL ::= ? your platform's EOL character or sequence ?
white space ::= { ? any non-EOL whitespace character ? }
digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
non-zero digit ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
  • tf command can be any valid tf command, such as get, workfold, and workspace.

  • tf option can be any valid tf option, such as -login, -profile, and -format.

  • tf free argument can be any string that is intended as a free argument to tf, such as a server path and a local path.

  • positional argument is a placeholder for text that is substituted from the outer tf command-line arguments. The number is a positive integer that corresponds to the index of the command-line argument that you want to substitute, such as "%1" and "%2". %1 refers to the first argument. You can use positional arguments as options or free arguments and in any order after the command.


Use double quotation marks to surround options and arguments that contain spaces. For example, use “-version:LRelease 2.1” for a label specifier, “$/Inventory/Client Project/main.c” for a free argument, and "%1" for a positional argument that may contain spaces. Only double quotations denote option boundaries in command files. Single quotations are interpreted literally. To specify a literal double quotation in your action line, you must use two double quotations together (""). Quoting rules inside command files may differ from the rules that your shell uses because your shell does not parse the lines in the command file.

Community Additions