Writing command templates

A command template is a line of text with placeholders in it. When you act on a project, the placeholders are replaced with that project’s values and the result is copied to your clipboard. That is the whole mechanism, and understanding it is enough to make ProjectShelf do almost anything.

The placeholders

The command editor lists all of these and inserts them at the cursor, so there is nothing to memorise. A placeholder for a field you left empty is substituted with an empty string rather than being left as literal text, except where a sensible default exists, as with the branch and package manager.

Quote your paths

Paths contain spaces more often than not. Every built-in template wraps the path placeholder in double quotes, and yours should too. Without them the shell reads the path as several arguments and the command fails in a confusing way.

code "{path}"
code {path}

The first survives a folder called My Client Work. The second does not.

Multi-line templates

A template can be several lines. They are copied together as one block, which is the point: you should never have to paste twice to accomplish one thing.

cd "{path}"
{packageManager} install
{devCommand}

Select six projects and this produces eighteen lines in the right order, ready to paste into one terminal.

Attaching a template to a tool

Each command has a "Belongs to" field naming a terminal, editor, or application. That connection is what makes the command system configurable rather than decorative: when you use the Open in terminal action, ProjectShelf looks for an enabled command attached to the terminal it resolved, and uses it. Only if there is none does it fall back to a plain directory change built from that terminal’s prefix.

1. A command attached to the resolved tool, if one is enabled.
2. The tool’s own launch template, for editors and applications.
3. A directory change built from the terminal’s configured prefix.

Set "Belongs to" to Any tool for commands you only want to reach through the generate-commands dialog, such as a build or a deploy.

Worked examples

cd "{path}" && git status --short

cd "{path}" && git pull --ff-only origin {branch}

start "{github}"
start "{url}"

cd "{path}"
git switch -c chore/{name}-cleanup

cd "{path}" && devcontainer open .

Order and enablement

Commands can be reordered and disabled. Order matters when several commands are attached to the same tool, because the first enabled one wins. Disabling is the reversible alternative to deleting, and it is the right choice for a preset you might want back.

What this cannot do

ProjectShelf produces text. It does not execute it, cannot execute it, and does not check whether the command is sensible. That is a deliberate boundary: the tool is useful precisely because nothing happens on your machine until you decide it should. Read what lands in your clipboard before you run it, exactly as you would with anything copied from a web page.