Skip to Content
CommandsTools and repo setup

Tools and repo setup

pf tools

Some repos have their own developer CLI: an executable a at the root, a cli/run entry and cli/commands/**/*.sh scripts whose headers carry # desc: and # usage: lines. pf reads it.

pf tools # list the repo's tools pf tools seed # run one pf tools seed --reset # extra arguments go to the tool pf tools --dry-run

A command named like a task (dev, build, test, lint, install or setup) becomes that task’s repo script, so pf dev runs it. deploy:staging and deploy:production become deploy targets (-y is added when its usage mentions it, since pf already confirmed). Everything else is reached with pf tools.

pf actions

pf actions lists what this repo can do, the same things the menu offers, as actions: each has an id, a tooltip label, a codicon  name and a featured flag. Editors draw the featured ones as small icon buttons; the Background Tone extension shows them on the Repo Identity card.

pf actions # the featured actions pf actions --all # every action; * marks the featured ones pf actions --json # for editors: {"schema":1,"repo":"...","actions":[...]} on stdout pf actions feature build # make "build" a button pf actions feature seed --icon database pf actions unfeature install:local pf actions feature build --dry-run
IdRunsIconFeatured by default
devpf devplayno
deploy:stagingpf deploy stagingrocketyes
deploy:productionpf deploy productioncloudyes
deploypf deploy (a repo’s own deploy)rocketyes
publish:stagingpf publish stagingcloud-uploadyes
docpf docbookyes
build, test, lintpf build, …package, beaker, checklistno
install, install:<to>pf install [<to>]desktop-downloadno
toolspf toolstoolsno
git:pushpf git push (pf gp)repo-pushyes (the repo needs a git remote)
a custom commandpf <name>terminalonly with "featured": true

Only what the repo really has is listed, so a repo without a staging target has no deploy button. Production deploy and publish still ask before they run, because the button just runs pf in a terminal. Set featured and icon in pulpfixer.json; pf actions feature and unfeature write the actions section there, keeping the rest of the file. An older pf has no actions command, so the card shows a hint to update it.

pf git

pf git holds the git helpers for the repo. In a terminal it opens a menu: push, show the remotes, add or remove a backup remote, set the primary remote. Without a terminal it prints the remotes.

pf git push (short: pf gp) pushes the current branch to the primary remote, then to any backup remotes you set up on this machine, so a second repository stays a copy of the first. With nothing set up it is a plain push to the primary remote.

pf git # the menu (the remotes when piped) pf gp # = pf git push: the primary, then every backup remote pf gp --dry-run # show the git push lines, run nothing pf gp --no-secondary # the primary only, this once pf gp --tags # other arguments go to every git push pf git status # show the primary and backup remotes pf git backup # interactive: pick a remote or name a new one and give its URL pf git backup add backup git@example.com:team/repo.git # add the git remote and make it a backup pf git backup add mirror # an existing git remote becomes a backup pf git backup remove backup # stop pushing there (the git remote stays) pf git primary gh # push to "gh" first pf git primary origin git@example.com:team/repo.git # add the git remote and make it the primary pf git primary --unset

Add a backup remote with pf git backup (or “Add a backup remote” in the menu): it offers the git remotes the repo has that are not used yet, or a new one; for a new one it asks for the name (default backup) and the URL, runs git remote add and records it. A backup copies the primary, so a repo with no primary yet (no remote, or only a backup) is set up first: the wizard, pf gp and pf git primary in a terminal ask which remote is the primary, or for a name (default origin) and URL for a new one, and a backup that becomes the primary stops being a backup. Without a terminal pf git backup add refuses until pf git primary <remote> [<url>] has been run. From then on pf gp pushes to the primary, then the backup. Without a terminal give the arguments (pf git backup add <remote> <url>). Each interactive step prints the command that does the same thing.

  • Primary: the one in .pf/config.json, else the branch’s upstream remote, else origin, else the one remote that is not a backup (so a repo whose only remote is github pushes there). pf git status warns when none of these is a git remote of the repo. The first push of a branch (no upstream yet) is git push <primary> -u HEAD, since a plain git push origin would fail there.
  • Backup remotes get the same push as the primary: the current branch, by name. Nothing is deleted on them and there is no --mirror. -u goes to the primary only, so a backup never becomes the branch’s upstream.
  • A failing primary push stops everything. A failing backup is reported and the other backups still run; pf gp then exits with 1.
  • Extra arguments are git push options or refspecs, never a remote name, and go to every push. pf git push only pushes: it does not stage or commit.
  • The settings are machine-local, in the repo’s gitignored .pf/ folder (see Local settings), so another checkout or machine can push elsewhere. The remotes themselves are ordinary git remotes in .git/config.

The menu lists git for any git checkout, and git push (also pf actions id git:push) when the repo has a remote.

pf init

pf init # write pulpfixer.json from what was detected pf init --dry-run # preview pf init --ver # also set up versioning

See pulpfixer.json for the format.

pf repo

pf repo (short: pf rp) hooks pf’s helpers into a repo and wires its package.json:

  • config: renames an older pf.json to pulpfixer.json (the format is the same). A pf.json identical to an existing pulpfixer.json is deleted; one that differs is left alone with a warning, since pf reads only pulpfixer.json then;
  • link: gives pulpfixer.json an id and remembers the repo in pf’s state folder (below);
  • the /pnpm root commands: pnpm ask (every root script, grouped), pnpm doc (the docs site) and pnpm deploy:staging, adding the last two only where a docs site or a staging target exists;
  • /ver versioning: versions.json and pnpm ver;
  • background tone: sets bgTone.logo in pulpfixer.json from an image in the repo (logo.svg, assets/logo.png, public/icon.svg, else the first local image in the README) when it has none, never replacing one that is set, and offers to install the Background Tone extension into Cursor when it is missing (below);
  • local settings: adds .pf/ (machine-local pf settings, see Local settings) to the repo’s .gitignore, once;
  • deploy: tells you what pf d runs, or, when the repo has none, wires one (below).
pf repo --dry-run pf repo --list # every repo pf remembers pf repo --no-link # skip the link pf repo --no-pnpm # skip the pnpm commands pf repo --no-ver # skip versioning pf repo --no-tone # skip the background tone step pf repo --no-local # skip the .gitignore step for .pf/ pf repo --no-deploy # skip the deploy step pf repo --deploy # run the deploy setup even when pf d already resolves

It updates every older copy of the ver CLI, prints what it did and never commits. When everything succeeds it closes with the pulpfixer logo and a success message (just the message without a terminal). Run it again after pf update.

Background tone

The Background Tone extension (@pulpfixer/ext-bg-tone, part of the pulpfixer suite) tints a window and shows the repo’s logo so you can tell Cursor windows apart. It keeps its settings in the bgTone section of pulpfixer.json, which is committed with the repo. pf rp takes care of the repo side:

  • the logo: if bgTone.logo is empty, pf rp finds the repo’s image and writes it (pf rp --dry-run says what it would write). A logo you set yourself is never replaced, and one that points to a missing file is reported;
  • the extension: when Cursor does not have it, pf rp asks whether to run pf sys apply suite (default yes). Without a terminal it prints the command instead. When it is installed, pf rp reports its version and pf update keeps it current.

pf remembers a repo in two places:

WhereWhatIn git
pulpfixer.json idmy-service-3f9a2c1b: the repo name plus a random suffixyes
~/.pf/repos/<id>.jsonthe checkout paths, the origin remote (without credentials), the link revision and private settingsno

Settings that should not live in the repo, such as security-related ones, go in the record. The id connects the two, so moving the checkout or changing its remote keeps the record. pf rp creates both and refreshes the record. It reports the link as one of:

  • linked: pulpfixer.json and the record agree.
  • stale: the same repo, but the checkout moved, the remote or name changed, pulpfixer.json lost its id (pf finds the record by path or remote and writes the id back), or an older pf wrote the link. pf rp refreshes it.
  • unlinked: no id yet, or this machine has no record for it (a fresh clone). pf rp creates the record.
  • foreign: pulpfixer.json names a record that knows neither this path nor this remote, for example a copy or a pulpfixer.json taken from another repo. pf rp asks whether this is the same repo (share the record) or a different one (new id). Without a terminal it changes nothing. A foreign checkout never gets the record’s settings.

The link is still under development. Its format and rules change between pf releases (the link revision), so a linked repo sometimes needs pf rp again to update the connection. pf dev prints a hint when it does, and the agent sees the state in pf_commands.

Deploy setup

Some repos deploy through their own helper, not a script pf can read: triton’s ./tl d, arbiter’s ./al d. Those scripts have no # usage: headers, so pf cannot parse them. When pf d resolves to nothing, pf rp looks for helpers at the repo root (an executable script with a "$1" = "d" or "deploy" branch, ranked with the local GWLOCAL ones first and server-only ones such as arbiter’s a.sh last) and offers to start the coding agent with the bundled deploy-setup skill. pf asks which key to write, then starts Claude (or Cursor) in print mode so it exits when it is done and pf can show the result. Print mode streams its events (--output-format stream-json), and pf shows each step as it happens: what the agent says (│), each tool it runs with its main argument (▸ Read tl), any tool that fails (✗), and a closing line with the time, turns and cost. The agent:

  1. reads the repo’s own deploy notes (AGENTS.md, README, docs) and the helper;
  2. picks the dev-machine command and never a server-only one;
  3. writes the key you picked (deploy, deploy:staging or deploy:production; no terminal means deploy), with "message": true when the command commits and takes a commit message;
  4. never runs the deploy. It exits, and pf previews pf d.
{ "commands": { "deploy": { "run": "./al d", "message": true, "description": "Bump version, compile prefect.yaml, commit, push" } } }

After that pf d asks and runs ./al d, and pf d "fix login" runs ./al d 'fix login'. Without a terminal pf only prints the hint (pf rp --deploy).

Last updated on