tsh Commands

The basics of how to operate tsh.

Updated 2018-10-09T12:05:00+05 for tsh 3.340.

How to Enter Commands

tsh is a command shell. If you’re familiar with using shells such as any Unix shell, OS/X Terminal or even DOS, you can probably skip this paragraph. A command shell is a no-frills way of interacting with a computer. In a large window, the computer displays a prompt, inviting you to type in a command that the computer understands. When you do so and then press the “return” key (analogous to hitting your clock in Scrabble), the computer takes some action based on what you’ve entered, then prompts you for your next command. Sometimes your command is modal, causing the computer to prompt for and expect a different set of commands until the mode is complete.

Pay attention to the changing prompts, which indicate what information tsh needs. Don’t forget to press the “return” key to confirm each command.

If you make a mistake and want to correct a previous command, or if you just want to repeat it, you may (depending on your system configuration) be able to scroll back by using the arrow keys on your keyboard. If pressing the arrow keys instead adds garbage to your screen, you can’t, but might consider installing the appropriate Term::ReadLine module that got left out of your Perl distribution (for OS/X users it's Term::ReadLine::Perl).

If you want to enter more than one command on a line, separate them with semicolons. Each one will be executed in turn before you are returned to the main prompt.

The Most Important Commands

The most important commands to remember are “quit”, “help” and “huh”.

Quit

The “quit” command makes tsh stop running.

HELP

If you’re not sure how to use a command, then try typing “help the-name-of-the-command”. Here’s an example, showing what one version of tsh shows when you enter “help help”:

Usage: help topic

Use this command to view built-in documentation.  For fuller details, please
consult the HTML reference manual.  Enter “help index” to see a list of
available commands, and “help” followed by a command name to find out more
about that command. 

The first line tells you that when you use the “help” command you are expected to enter a topic after the word “help” so that tsh will know what you are asking for help about. Most commands require some supplementary information (called arguments) such as a division name, round number or player number.

The DOCumentation command opens a web browser to this reference documentation. If you enter “doc”, a window should appear displaying this manual’s introductory page.

HUH

If you’re not sure what a message means, and it has a code in [square brackets] after it, enter “huh the-message-code”. Again, messages are documented in this way, and soon all of them will be. If you enter “huh” on its own, the last message you saw will be explained. To take a mostly random example, if you saw the message “If you are sure you want to pair Round 12 based on Round 10, please specify config session_breaks. [eacpnsb]” you might want to know more and enter “huh eacpnsb”. You would then see the message:

[eacpnsb] It looks like you are relying on the default Chew pairing system, but
the program is not sure whether you wanted to compute pairings for the upcoming
round based on the first or second preceding round.  You can resolve the
ambiguity by setting a value for the configuration variable 'session_breaks' in
your configuration file. 

This tries to explain the original, brief message. If neither the detailed explanation nor the related documentation is clear to you, please ask John to provide further clarification.

tsh Command Reference

All currently available tsh commands are listed below in tables for reference, grouped by function. Most users will not use most of these commands. Each command has a name which verbosely describes its purpose, but which can be abbreviated to the portion shown in capital letters as shown in its example. Most commands must be followed (on the same line, before pressing “return”) by one or more arguments. These arguments are represented in examples by names, which must be replaced by actual values. If you don’t enter correct arguments, tsh will tell you what the correct ones should be, and where it stopped understanding what you were typing. Within modal commands, the syntax of what you are supposed to type varies, but is usually shown in the prompt.

To take one case, the example for the “RoundStandings” command, which displays standings in a division as of a specified round, reads rs r d. This means that “RoundStandings” can be abbreviated to its capitalised letters “rs”, and that it must be followed by a round number and a division name. You would enter “rs 5 b” and press the “return” key to ask for Division B standings as of Round 5. If you have only one division in your tournament, you may omit division names as arguments to commands. In the preceding example, you would just enter “rs 5”.

If you can’t remember a player number, you may enter enough of the player’s last and/or first names to unambiguously identify them, joined by a comma. For example, if “Chew, John” is the only player who has “HEW” in their last name, then you can see his scorecard by typing “sc hew,”. The comma is optional if you include at least two letters from one of the player’s names. As of the current release, this is not consistently implemented in modal commands such as the “Addscore” command, where the comma is not optional.

Data Entry Commands

The following commands are used for entering tournament results, as well as checking and correcting them:

CommandExampleDescription
Addscorea r dBegin entering new game scores for round r, division d. This command is modal, and keeps prompting for scores until you press “return” on a line without scores.
CheckRoundScorescrs r dList all entered scores for round r, division d, to facilitate checking of data entry.
DELETEscoredelete p1 s1 p2 s2 r dDelete the previously entered scores s1 for player p1 and s2 for player p2 in round r division d. To delete a forfeit or bye, enter the spread as s1 and 0 for p2 and s2. This syntax is intentionally verbose to discourage the use of this command.
EditScorees d p rBegin editing previously entered game scores, starting with player p in round r, division d. This command is modal and fully documented in the data entry section.
FIXfix d p(Experimental) Begin graphically editing previously entered game scores for player p in division d.
ForfeitLOSSfloss d pn r sprDelete any previous pairings for player pn in division d for round r and instead assign them a forfeit loss with a spread of spr. If the spread is omitted, use a default value
MISSINGmissing r divList all players in division div whose round r scores have not yet been entered. If div is omitted, all divisions are included.
showScoreCardsc d pShow the correct scorecard for player p in division d, for checking.

Report Generation Commands

The following commands generate reports based on tournament results. You can use the “Browse” command to open your web browser to an index page showing what reports you have generated so far. The “BrowseLast” command opens your web browser to the most recent report that you requested, so that you can easily print it.

A round may be specified to indicate pairing bars should apply to a round other than the latest for which pairings exist. A round may be specified to indicate pairing bars should apply to a round other than the latest for which pairings exist.
CommandExampleDescription
ABSPgridabsp [d...]Shows a results grid suitable for submission for ABSP ratings. Omit divisions unless you only want to submit results from some division.
AUPAIRaupair dCreates a .TOU file named for the division, containing ratings input information in AUPAIR.EXE format.
AverageOpponentScoresaos divList average opponent scores for all players in a division.
AVEragesave divList average scores for all players in a division.
EnhancedScoreBoardesb dCreate an HTML-only scoreboard that uses AJAX technology to dynamically display division d.
HighCombinedhc n divList top n high combined scores (of both players in a game) in a division.
HighLosshl n divList top n high losing scores in a division.
HighRatingChangeshrc divList the players whose ratings have increased by the most in a division.
HighRoundLosseshrl r1-r2 divList the high losing score in each round in a range of rounds in a division.
HighRoundWinshrl r1-r2 divList the high winning score in each round in a range of rounds in a division.
HighSpreadhs n divList top n high spreads (winning margins) in a division.
HighWinhw n divList top n high winning scores in a division.
LowCombinedlc n divList top n low combined scores (of both players in a game) in a division.
LowLossll n divList bottom n low losing scores in a division.
LowSpreadls n divList top n low spreads (winning margins) in a division.
LowWinlw n divList bottom n low winning scores in a division.
luckySTIFFstiff n divList players according to the total of their n closest wins, the opposite of a TUFFluck prize.
PRiZesprizes dList all prizes to be awarded, based on current division standings.
RATingsrat dShow current division standings (with ratings estimates) for division d. See the “config rating_system” option.
ResultsByRoundrbr r1-r2 dRank players in division d based only on rounds r1 through r2, typically to compute “best results, day n” prizes.
ROSTERSrostersList all players, with their player numbers and ratings.
ROTOroto rList rotisserie standings as of round r (if omitted, the current round).
RoundClassRATingsrcrat r1-r2 dShow standings with ratings estimates for division d as of round r2, and refresh report files for rounds r1 through r2-1, grouping players by class. The “r1-” is optional.
RoundHandiCaprhc r1-r2 dShow Thai handicaps in rounds r1–r2 for division d.
RoundRATingsrrat r1-r2 d [r]Show standings with ratings estimates for division d as of round r2, and refresh report files for rounds r1 through r2-1. The “r1-” is optional.
RoundStandingsrs r dShow standings for division d as of round r.
saveJSONjson dUsed internally to store the state of a division on a web server, in a form usable by the “EnhancedScoreBoard” command. Often used with the “hook_addscore_flush” and “hook_autopair” options.
ScoreBoardsb d rk1 rkn size cols secsCreate an HTML-only scoreboard showing what is going on in division d between ranks rk1 and rkn with player photos (where available) scaled to size pixels wide in cols columns refreshed automatically every secsseconds. Often used with the “hook_addscore_flush” and “hook_autopair” options.
SHOW12show12 dList firsts and seconds for all players in a division.
ShowDivisionScoreCardssdsc dGenerate in HTML form the scorecards for every player in division d, for printing and distribution at the beginning of the tournament.
ShowManyPairingssmp r1-r2 dShow pairings for rounds r1-r2, division d.
ShowNextPairingssp dCreate an HTML report of pairings for the "next" round in the specified division, where "next" is the round following the lastest one for which scores have been entered, or round 1 if none. A single-round report of pairings for this round must already have been generated using ShowPairings. This command is intended to be used in conjunction with config pairings_refresh and config hook_division_update to provide an automatically-updating pairings display.
ShowPairingssp r dShow pairings for round r, division d.
STandingsst d [r]Show current standings for division d.
showRankedWallChartrwc dShow ranked wall chart for division d, as a summary of the entire tournament state.
showWallChartwc dShow correct wall chart for division d, to check against the physical chart.
SPITroastspit r dList UK rotisserie standings for division d as of round r.
STATisticSstatsReport on summary statistics for a tournament.
TeamStandingsts dShow current team standings for division d.
TOTalScoretots divList players ranked according to the total number of points each has scored.
TotalTeamStandingsttsShow current total team standings across all divisions.
TUFFlucktuff n divList players according to the total of their n closest losses, for the NSA’s “Tuff Luck” prize.
UPSETsupset dShow ratings upsets for division d.

Pairing Commands

The following commands are used mainly for manually pairing rounds. You will need to know about them if you are configuring tsh before a tournament, or if you encounter an unexpected pairing situation and want to override automatic pairings. See the section on pairing theory for more detailed information about pairing systems.

CommandExampleDescription
AssignTeamsSnakedats r n dAssign players to teams, usually so that you can then avoid pairing them with each other in early rounds using the “exagony” configuration option. You might instead want to use the TeamRoundRobin or TeamMultipleRoundRobin commands to have each player play players on other teams. The n teams will be called ‘GrpA’, ‘GrpB’, ‘GrpC’, ... in snaked (boustrophedonic) order (i.e., the top n players in division d as of round r (0 for pre-event seedings) are assigned to teams in order, the next n in reverse order, then forward again, etc.).
BASDFinalbasdf r dAdd Round r of BASD final pairings to division d.
BASDSemibasds dAdd three rounds of BASD semifinal pairings to division d.
BRACKetpairbrack n dSet up pairings for single-elimination with n repeated pairings in each stage for division d.
CAMbridgePaircamp dSet up seven-round pairings as used in Cambridge ON for division d.
ChewPaircp sr dSet up Chew Pairings in division d based on round sr standings.
FactorPairfp rd rpt sr dPair players permitting rpt repeats based on sr standings in division d, optimally matching players whose ranks differ by rd.
GREENgreen dSet up pairings as used by John Green for division d.
GUELPHguelph dSet up pairings as used in Guelph ON CAN for division d.
InitFontesif nr dSet up fixed pairings for nr rounds (typically 3) in division d to give later Fontes pairings a place to start. Players are randomly chosen from quartiles and paired in round-robin quads.
KOTHkoth rpt sr dAdd king-of-the-hill pairings allowing rpt repeats (0 for none, 1 for simple repeats, 2 for threepeats), based on round sr standings in division d. To restrict the number of repeats after a certain round, e.g., KOTH pairings based on round 10 standings with no repeats after round 8, use koth 0>8 10 a.
LowerRoundRobinslrr rk rds dAdd rds rounds of round robin groups pairings to division d starting at rank rk, allowing any number of repeats.
NASTnast dAdd 4 or 5 rounds of fixed NAST pairings.
NewSwissns rpt sr dAdd a round of Swiss pairings. See KOTH above for descriptions of arguments.
PAIRpair p1 p2 r dManually pair players p1 and p2 in round r, division d. Use “0” as the player number of the opponent of a player with no opponent.
Pair1324p1324 rpt sr dPair 1–3, 2–4, 5–7, 6–8, and so on, i.e., factored pairings with factor two. Some people call it QOTH or Queen-of-the-Hill pairings. See KOTH above for descriptions of arguments.
PairManypm r dBegin manually pairing a large number of players in round r, division d. This command does not assign firsts, use PairMany12 if you need to specify the order of play. This command is modal.
PairMany12pm12 r dBegin manually pairing a large number of players in round r, division d. If you are tracking firsts and seconds, the first player entered goes first. This command is modal.
PairQuartilespq q rpt r dPair the top quartile at random against quartile q, based on round r, with at most rpt repeats, in division d.
RandomPairrp rpt sr dAdd a round of random pairings to a division.
RoundRobinrr n dAdd a full round robin to a division. If n is specified, it is the number of times each player should play each opponent consecutively; n defaults to the value 1.
TeamRoundRobintrr n dPair each player in division d with every player on every other team. If n is specified, have them play each other n times in succession. tsh will use a fixed algorithm to schedule players; you can shuffle this by specifying an order other than “1,2,3,...,2t” for the value of the “config round_robin_order” configuration option.
TeamMultipleRoundRobintmrr rpt n dDivide each team in division d into squads by standing as of round n, then pair each player with every player in the corresponding squad of every other team, in a round robin schedule that runs for n rounds. You should normally do this when the last paired round is fully paired; if it is partially paired, only the unpaired players will be involved in the team multiple round robins.
UnPairRoundupr r dDelete all round r pairings from division d. Only the last round’s pairings may be deleted, and only if no scores have been entered. Use DELETEscore to delete scores, or edit the “.t” files directly.

The following pairing commands are deprecated, but are listed in case there is anyone who is still using them. All of these commands have been replaced by NewSwiss, which produces much better quality Swiss pairings.

CommandExampleDescription
BYEbye p s r dDeprecated: use PAIR and Addscore instead.
PrePreSwissppsw rpt p1 p2 dDeprecated: use NewSwiss instead.
PRESWissppsw rpt p1 p2 dDeprecated: use NewSwiss instead.
SWisssw rpt sr dDeprecated: use NewSwiss instead.

Testing Commands

The following commands are used mostly for testing your tsh configuration before your tournament begins.

CommandExampleDescription
DEBUGdebug code levelTurns debugging for sections labelled with code on if level is 1 or off if 0. Examine the tsh source code to find applicable codes.
DRYrundry r dSimulates an entire tournament for a division, using random data and whatever pairings you have configured. If you specify a round number, the simulation begins after that round, and you must have exactly that many rounds completed in your data files. If you omit the round number or give it as 0, the simulation begins at the start of the tournament.
EVALeval codeEvaluate arbitary perl code. Use only if you know what you’re doing.
RANDomscoresrand d...Give each player in division d a random score, to help simulate a tournament’s pairing system. Entering more than one division acts on each division, entering a division name more than once adds more than one round’s worth of random data.
RESETEVERYTHINGreseteverythingDelete all pairings, scores, start information and board assignments from tournament data files, and delete all journal and print files. Use with extreme caution.
TRUNCATEROUNDStruncaterounds r dDiscards all data in a division after the given round (if 0, discard all data). Use with caution.

Miscellaneous Commands

And here all the commands which don’t fit into one of the above categories:

CommandExampleDescription
BUGreportbug note describing what went wrongUploads information about your TSH event to a webserver, along with a note explaining the problem, which all then gets sent to John Chew.
BrowsebOpens your web browser to the tournament report index.
BrowseLastblOpens your web browser to the last report you generated.
DivisionCompletedc bManually triggers the commands given in the “config hook_division_complete” configuration option.
EXPORTRATINGSexportratingsCreates a copy of the ratings database used by the “USERATINGS” command including the results of the current tournament.
HELPhelp topicDisplays builtin documentation. topic is typically a command name.
HUHhuh codeGive a detailed explanation of a diagnostic message that included a [code].
LISTTourneyslisttList all pending unrated tournaments (in realms that support this), so that you can find a value for the “tournament_id” configuration parameter.
LOOKl wordLook up word in dictionary. CSW 2012 and TWL 2006 lexicon files available as a separate download. See also the “count_good_words” configuration option.
PROFILEprofile set key valueSet the value of configuration option “key” to “value” in your user profile.
profile showShow all configuration options and values defined in your user profile.
QuitqQuit tsh.
setESBMeSsaGeesbmsg set Games resume after lunch at 3:15Display a message on the Enhanced Scoreboard which optionally hides the ESB if the message mode is set to "hide" (the default mode is "reveal"). Three subcommands are recognized: "set" sets the message text; "mode" followed by "hide" or "reveal" sets the message mode; "off" turns off the message and reveals the ESB if it was hidden. Without any subcommand, reveals the current state of the ESB message.
SUBMITsubmitSubmit ratings data to the NSA web site.
TWEETtweet d p1 p2Report to twitter about how players ranked p1 through p2 are doing in division d.
UPDATEupdateUpdate tsh software using a web connection.
UPDATEPIXupdatepixUpdate the local photo database used by the “ShowPairings” command. Photos are copied from the local photo database into the ‘pix’ subdirectory of the event’ HTML directory when tsh starts up.
UpdatePLAYersuplayUpdate the player roster by referring to cross-tables.com. This will replace both player names and ratings; you may then wish to use the USERATINGS command to update just the ratings, if they haven’t yet been updated on cross-tables.com.
UPDATERATINGSupdateratingsUpdate the ratings database used by the “USERATINGS” command, currently available for the NASPA (NSA) and ABSP realms.
USERATINGSuseratingsUpdate all player ratings using the ratings database most recently updated by the “UPDATERATINGS” command.
VALETvalet d p r(Experimental) Open a browser window for data entry.

Plug-In Commands

There may also be external (plug-in) commands installed in your particular copy of tsh. These will be in a directory called ‘bin’, and listed in a configuration file there called ‘tshxcfg.txt’. They have been tested with OS/X (and should therefore work with most other flavours of Unix) and Windows XP, but may not work with more primitive operating systems. If not, you may still be able to use externals by running them separately from the command line. The following externals are part of the default distribution.

CommandExampleDescription
maketmmaketm divMake a TourneyMan data file for a division.
nsscnssc divList School Championship prizes for a division.
update-dictupdate-dictUpdate the lexica (word lists) used by the LOOK command.
Some commands come bundled in plug-in modules:
ModuleCommandExampleDescription
TSH+LoadplayersCsVlcv dLoad division data from an appropriately named CSV data file.
TSH+MergeplayersCsVmcv dMerge division data from an appropriately named CSV data file.
TSH+SaveplayersCsVscv dSave division data to an appropriately named CSV data file.

Utility Commands

There are also a number of standalone utilities found in the “util/” directory, which are currently provided on an as-is basis. They are ‘standalone’ in that they have to be run in a separate window from tsh. Documentation will be provided here for any command upon request.

CommandExampleDescription
mirror-ftpmirror-ftp -u username -p password event-name...

This separate program will mirror (constantly copy as needed) your TSH report files to your webserver using the FTP protocol. Use it to publish your tournament’s results live to the Internet. If you do not have a webserver, email poslfit@gmail.com to have one set up for your event.

Because this is a separate program, you will typically need to run it in a separate window (COMMAND/DOS in Windows, Terminal in OS/X, some sort of term window in other flavours of Unix). Windows users should try running one of the .bat script files in the util folder (such as mirror-ftp.bat); others should open a window, cd to the tsh directory, and run “util/mirror-ftp” with command-line arguments as described below. Under most circumstances, the program will keep running without further attention. You should kill it when you are done with it (typically using Control+C); if you change Internet connections while it is running, you may need to kill and rerun it.

This script needs to know five things to run. They can be specified in various ways.

Tournament(s)
Specify this the same way as when you are running tsh. If you don’t specify a tournament, the one whose config.tsh file is newest will be used. To explicitly specify one or more tournaments, list their directory names at the end of the command line (this only works when invoking the program from the command line). Unlike tsh, this program can work with multiple simultaneous tournaments.
FTP Host
You must specify your FTP host name (or IP address) in your config.tsh file using the “ftp_host” configuration parameter.
FTP Path
You must specify the directory path of your TSH coverage folder/directory on your webserver’s FTP system in your config.tsh file using the “ftp_path” configuration parameter. Your files will be copied into a subfolder/subdirectory of this path, named the same as the folder/directory containing your local copy of your event.
FTP Username
You may specify the username that you use to log onto your FTP account in three ways: using the “ftp_username” configuration parameter, using the “-u MYUSERNAME” command-line option, or having the program prompt you for your username. The last way is the most secure; the second way is secure if your local computer is secure.
FTP Password
You may specify the password that you use to log onto your FTP account in three ways: using the “ftp_password” configuration parameter, using the “-p MYPASSWORD” command-line option, or having the program prompt you for your password. The last way is the most secure; the second way is secure if your local computer is secure; the first way exposes your password to the Internet and is not recommended.

“util/mirror-ftp” uploads the following files: the event config.tsh file, each division’s ‘.t’ file, and the contents of the directory specified by the ‘html_directory’ configuration option. Files ending in ‘.css, ‘.html’, ‘.htm’, ‘.t’ or ‘.txt’ are sent in text (ASCII) mode; others are transmitted in binary mode. “util/mirror-ftp” decides whether or not a file is stale and needs to be transmitted by comparing it to a zero-size file of the same name in ‘flags/event-name’ in the tsh directory.