Custom commands

Custom Commands are entries you add to the right-click menu yourself: give one a name, a program to run and a line of arguments, and from then on right-clicking a file shows that entry at the bottom of the menu, handing the selected files to that program. This page covers how to add one, how to write the arguments, and when a command appears in the menu.

These are not the same thing as the shell extensions tessoa picks up from the system: those are installed by other software, these are written by you.

Adding a command

1. Press Ctrl+Shift+P (macOS: ⌘+,) to open Settings.
2. Find the Input group and click Custom Commands.
3. Click + Add command, or click + Add from a template… and pick one from Common commands — a template fills in the whole form, and you can still change anything afterwards.
4. Fill in Name and Program. Choose… at the end of the Program row lists the programs found on this machine; you can also type a full path.
5. Fill in Arguments, x %1 -o%D for example.
6. Click ‹ Back to return to the command list. Changes take effect immediately, with no restart.

A new command appears at the very bottom of the right-click menu, in a section of its own. To move it elsewhere, use the context menu order page.

Under the header of the command list there is a Filter commands… box, which beats scrolling once you have a few dozen. Rows cannot be dragged while the filter is on — row 3 of a filtered view is not entry 3 of the table, so a drag would land in the wrong place. Clear the filter first, then reorder.

What each field does:

Field	What it does
Name	The text shown in the menu. A command with no name would be gone after a restart, so it cannot be cleared
Program	The executable to run. Without it the command stays in Settings but never shows up in the menu
Arguments	The argument template passed to that program, see the next section
Applies to	Wildcards separated by ;, *.zip;*.7z for example. Empty means any file
Show on	Files, Folders and Empty space can each be turned on separately
Multiple selection	One process, all items or One process per item, see below
Console window	Hidden or Shown. Choose Shown for command-line tools whose output you want to watch
Confirm before running	Opens a box on every click, spelling out the exact command about to run
Enabled	Turning this off hides the command in all four menus, but keeps it in Settings

Below Arguments sits a Preview that expands the command against whatever you have selected right now, and Test run runs exactly what the preview shows. A mistake in the arguments is visible here, without closing Settings and right-clicking to find out.

Placeholders in the arguments

These markers in the argument template are replaced with real paths. The first four match what File Explorer uses.

Placeholder	Replaced with
%1	The full path of the first selected item
%*	Every selected item, expanded into separate arguments
%D	The folder %1 is in
%N	The file name without its extension
%E	The extension, without the dot — so %N.%E rebuilds the original name
%V	The folder you right-clicked in
%W	The working directory, which is also the current directory handed to the program
%%	A literal %

Markers that aren't recognised are left as they are, so something like %APPDATA% passes straight through.

Note

Arguments are split on spaces, one per field. Wrap a part containing spaces in double quotes, and write two of them in a row for a literal quote. Backslash is not an escape character, so C:\Program Files\7z.exe can be written as it is.

Multiple selection decides how many processes start

With three files selected and the command written as ffmpeg -i %1 -y %D\%N.webp:

Multiple selection	Processes	Result
One process, all items	1	Only the first file is processed; the other two are never mentioned
One process per item	3	Each of the three files is converted

Which one is right depends on whether the program takes more than one input: VS Code does (code %* opens three files in one process), ffmpeg does not (-i takes a single input). There is no safe default here, so give this field a thought before you save.

Under One process per item two limits apply when the selection is large: above 20 items a box asks you to confirm, and above 200 the command refuses to run and suggests One process, all items with %* instead.

When a command stays out of the menu

A command that doesn't qualify is left out entirely, rather than shown and failing when clicked. Any one of these keeps it out of this particular menu:

• Name or Program is empty, or Enabled is off.
• What you right-clicked is not covered by Show on. For example, only Files is ticked and you right-clicked a folder.
• One of the selected items does not match the Applies to wildcards. Every item has to match, not just one of them.
• You right-clicked inside an archive or on a connected phone, where items have no real path on disk and an external program could not open them anyway.
• The arguments use something this spot does not have. The tag view has no "current folder", so commands using %V do not appear there; right-clicking empty space selects nothing, so commands using %1 do not appear either.

What happens after it runs

Clicking a command puts a message in the lower-right corner saying how many processes started — with Console window set to Hidden nothing else happens on screen, so this message is the only receipt.

tessoa then follows those processes for ten seconds. Anything that exits with an error inside that window produces a second message reporting the failure; anything still running after it (editors, browsers and the like) is left alone — the exit code from when you close it hours later says nothing about this command.

Every run is written to Activity, including the fully expanded arguments. When a command doesn't do what you expected, that is where you can see what it actually received.

Grouping into submenus

Once you have several commands you can file them into submenus: click + Add submenu to create one, then drag a command's row onto it in the list and let go. Drag it back out to return it to the top level. Order follows the same drag. Submenus are one level deep.

A submenu whose commands all fall out of the current menu is left out entirely, rather than shown as an empty box you can't open.

Where the commands are stored

All commands live in commands.ini next to your settings, and editing that file by hand works just as well:

[group.g_7z]
label = 7-Zip

[cmd.c1]
parent = g_7z
label = Extract here
exec = C:\Program Files\7-Zip\7z.exe
args = x %1 -o%D
on = file
match = *.zip;*.7z;*.rar
mode = each
console = hide
confirm = 0
enabled = 1

A broken block costs you that block only; the other commands keep working. Every command needs at least a label. exec may be left empty, which is the state of a command you just created in Settings but haven't pointed at a program yet.

Warning

tessoa does not know what your command does, so there is no undo. A custom command runs as a program of its own; whatever it deletes or rewrites is not covered by undo in Activity, and there is no progress bar. Turn on Confirm before running for commands that change files.

See also

Arranging the interface · Shell extensions · Settings reference · Activity