Repo commands

Create a command

qq create check pnpm typecheck

That writes infra/commands/check.sh, a plain shell script:

#!/bin/sh
# Created with `qq create check`; run it with `qq check [ARG ...]`.
# It runs from the repo root with the repo's pinned toolchains first on PATH;
# arguments given after the name reach it as "$@".
pnpm typecheck "$@"

Run it

qq check
qq check --pretty false    # extra arguments are passed on

It runs exactly like qq run: from the repo root, with the pinned toolchains first on PATH, whichever folder you are in.

Share it

Commit infra/commands/check.sh. Anyone who pulls gets qq check, and qq --help lists the repo's commands under qq's own:

this repo's commands (qq create NAME COMMAND adds one):
  check  pnpm typecheck "$@"

This is how a repo tells an agent how to work in it: the agent runs qq --help and sees the commands the team uses.

Arguments

• Created from several words (qq create check pnpm typecheck), each word stays one word, and the arguments you give qq check are added after them.
• Created from one argument (a quoted command line, or one word such as qq create lint ruff), it is saved as you typed it. Add "$@" where the arguments should go. Otherwise qq refuses to run it with arguments, rather than drop them silently.
• qq NAME --help shows the command when it takes no arguments; otherwise --help goes to the command.

Names

Names are lowercase letters, digits, - and _. qq's own command names, and names one typo away from them, cannot be created:

$ qq create snyc echo hi
qq: 'snyc' is one typo away from qq sync, so a mistyped qq sync would run it; pick another name

That way a mistyped qq sync never runs a repo's code. To replace a command, use qq create --force NAME COMMAND.