create-pools
Generates a Pools & Knockout bracket: round-robin pools followed by a knockout elimination tree.
Flags
| Flag | Short | Default | Description |
|---|---|---|---|
--file |
-f |
(none) | CSV file with participants (required) |
--output |
-o |
(none) | Output .xlsx path (required) |
--courts |
-c |
2 |
Number of shiai-jo (courts) to distribute pools across. Must be 1, 2, 4, 8 or 16; refer to Shiai-jo count |
--players |
-p |
3 |
Minimum players per pool. Mutually exclusive with --max-players. |
--max-players |
-m |
(none) | Maximum players per pool. Mutually exclusive with --players. |
--pool-winners |
-w |
2 |
Players that qualify from each pool; refer to Qualifiers per pool |
--extra-qualifiers |
(none) | "" |
Send extra qualifiers from oversized pools, or fit pool sizes exactly to the bracket; refer to Extra qualifiers |
--round-robin |
-r |
false |
Force full round-robin in every pool |
--team-matches |
-t |
0 |
Players per team (0 = individual tournament) |
--with-zekken-name |
-z |
false |
Use second CSV column as zekken display name |
--seeds |
(none) | (none) | CSV file with seed rankings |
--determined |
-d |
false |
Do not shuffle input order |
--single-tree |
(none) | false |
Produce one tree sheet instead of one per court |
--number-prefix |
-n |
(none) | Letter prefix for competitor numbers (for example, K produces K1, K2, …). When omitted, one is derived from --title-prefix; if --title-prefix is also omitted, the prefix is K. The CLI derives this from --title-prefix alone, with no knowledge of any other competition, so running this command more than once for the same tournament without a distinct -n each time produces the same K1, K2, … tags for every one of them; pass a distinct -n per competition (the tournament mobile app, unlike this command, checks prefixes already in use and avoids them automatically) |
--title-prefix |
(none) | "" |
Prefix added to sheet titles |
--third-place-match |
(none) | false |
Play a 3rd-place (bronze) match after the semifinals, deciding a single 3rd place. Kendo's default is two joint 3rd places with no bronze match |
Examples
Minimal: two courts, random draw:
Four courts, pools of up to 5, top 2 qualify, full round-robin:
Team tournament (3 players per team, 2 courts):
With zekken names and seeding:
Shiai-jo count
--courts takes 1, 2, 4, 8 or 16. The elimination tree gives each shiai-jo its own block of the bracket. The blocks then merge in pairs, so the count has to halve cleanly all the way down. Any other value stops the command with an error naming the counts to use instead, and the error always offers 1.
Being even is not enough on its own. With -c 6 the six blocks pair off into three, but three cannot pair off again. One of them would then reach the final having fought a round fewer than the other two. -c 6 and -c 10 are therefore refused, just as -c 3, -c 5 and -c 7 are.
A single shiai-jo is always allowed. With two or more qualifiers per pool (-w 2 and above), -c 1 splits its block into two halves that act as partner shiai-jo, producing the same bracket shape as a -c 2 run. With -w 1, nothing crosses between shiai-jo: the block stays whole, and each bye is chosen from every pool winner on it. 16 is the highest. It is also the most shiai-jo a tournament can have, so 32 is out of reach.
The draw also never uses more shiai-jo than there are pools, because a shiai-jo with no pools of its own would own an empty block. When you ask for more, the count steps down to the largest allowed value that fits. The file is generated without an error: with 7 pools, -c 8 produces a draw on 4 shiai-jo.
This is a per-tournament-file rule, not a rule about your venue. A hall with three shiai-jo generates one file for two shiai-jo and another for one, and runs both at the same time. Refer to How many shiai-jo a competition can use for the full explanation.
Qualifiers per pool
--pool-winners sets how many players advance from each pool into the elimination tree. It also changes the shape of the draw, because each shiai-jo gets its own block of the bracket and shiai-jo are paired up into opposite halves:
-w |
What happens in the draw |
|---|---|
1 |
Nothing crosses. Every qualifier is its own shiai-jo's pool winner and stays in that shiai-jo's block, so first-round matches are between pools of the same shiai-jo. |
2 |
Pool winners stay in their own shiai-jo's block; runners-up cross to the partner shiai-jo's block. Partners are in opposite halves, so a pool's two qualifiers can only meet in the final. |
3 |
As for 2, plus the third qualifier crosses to the other pair of shiai-jo, in the half that does not hold the pool winner. All three land in different quarters of the draw. |
Higher values continue the same rotation, but a bracket has only four quarters. From the fifth qualifier per pool onward, two of a pool's qualifiers must share one.
Byes follow from the size of each block, not the total field. A block with an even number of competitors gets none. A block with an odd number gets exactly one, awarded first to a seeded pool's winner. Refer to The knockout draw for the full rules and worked examples.
Extra qualifiers
--extra-qualifiers changes how many finishers each pool sends up, instead of every pool sending the same number:
| Value | Behaviour |
|---|---|
"" (default) |
Standard: every pool sends --pool-winners qualifiers; unfilled bracket slots become byes. |
larger-pools |
A pool larger than the minimum pool size sends one extra qualifier, crossed to a neighbouring shiai-jo, on top of the usual number. It always fights in the first round and never byes. |
fill-bracket |
Pools are cut so that pool winners, plus a handful of drafted second places, exactly fill the bracket with no byes. The drafts come from seeded pools in seed order (--seeds), with pools larger than the minimum as the fallback when there are not enough seeds. |
Both larger-pools and fill-bracket require -p (minimum pool size, not -m) and -w 1; the command refuses any other combination. Refer to How many qualify from each pool for the full explanation and worked examples, including when each mode can and cannot build a draw for a given entrant count and shiai-jo count.
Minimum pool size 3, one qualifier per pool, with the Oversized send +1 behaviour:
bracket-creator create-pools \
-f participants.csv -o tournament.xlsx \
-p 3 -w 1 -c 4 --extra-qualifiers larger-pools
Seeding
Seeding distributes top competitors so they land in separate pools and on opposite sides of each court's elimination bracket.
Create a seeds CSV:
Pass it with --seeds seeds.csv. Names must match the participant name exactly, including accents. Both lists are title-cased on read, so only differences beyond each word's first letter matter. Unseeded participants are placed randomly around the seeds.
The rank order matters in the elimination tree as well as in the pool draw. Seeds 1 and 3 land in one half, and seeds 2 and 4 in the other, each in its own quarter. Refer to Seeding in the knockout draw.
Output sheets
The generated Excel file contains:
| Sheet | Contents |
|---|---|
| Data | Raw participant list |
| Time Estimator | Expected duration per phase |
| Pool Draw | Pool assignments grouped by court |
| Pool Matches | Individual match schedule |
| Elimination Matches | Knockout bracket match schedule |
| Names to Print | A3-ready name labels |
| Tree (one per court) | Visual bracket tree for display |