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-runA 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| Id | Runs | Icon | Featured by default |
|---|---|---|---|
dev | pf dev | play | no |
deploy:staging | pf deploy staging | rocket | yes |
deploy:production | pf deploy production | cloud | yes |
deploy | pf deploy (a repo’s own deploy) | rocket | yes |
publish:staging | pf publish staging | cloud-upload | yes |
doc | pf doc | book | yes |
build, test, lint | pf build, … | package, beaker, checklist | no |
install, install:<to> | pf install [<to>] | desktop-download | no |
tools | pf tools | tools | no |
git:push | pf git push (pf gp) | repo-push | yes (the repo needs a git remote) |
| a custom command | pf <name> | terminal | only 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 --unsetAdd 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, elseorigin, else the one remote that is not a backup (so a repo whose only remote isgithubpushes there).pf git statuswarns when none of these is a git remote of the repo. The first push of a branch (no upstream yet) isgit push <primary> -u HEAD, since a plaingit push originwould 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.-ugoes 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 gpthen exits with 1. - Extra arguments are git push options or refspecs, never a remote name, and go to every push.
pf git pushonly 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 versioningSee 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.jsontopulpfixer.json(the format is the same). Apf.jsonidentical to an existingpulpfixer.jsonis deleted; one that differs is left alone with a warning, since pf reads onlypulpfixer.jsonthen; - link: gives
pulpfixer.jsonanidand remembers the repo in pf’s state folder (below); - the
/pnpmroot commands:pnpm ask(every root script, grouped),pnpm doc(the docs site) andpnpm deploy:staging, adding the last two only where a docs site or a staging target exists; /verversioning:versions.jsonandpnpm ver;- background tone: sets
bgTone.logoinpulpfixer.jsonfrom 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 druns, 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 resolvesIt 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.logois empty,pf rpfinds the repo’s image and writes it (pf rp --dry-runsays 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 rpasks whether to runpf sys apply suite(default yes). Without a terminal it prints the command instead. When it is installed,pf rpreports its version andpf updatekeeps it current.
The link
pf remembers a repo in two places:
| Where | What | In git |
|---|---|---|
pulpfixer.json id | my-service-3f9a2c1b: the repo name plus a random suffix | yes |
~/.pf/repos/<id>.json | the checkout paths, the origin remote (without credentials), the link revision and private settings | no |
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.jsonand the record agree. - stale: the same repo, but the checkout moved, the remote or name changed,
pulpfixer.jsonlost its id (pf finds the record by path or remote and writes the id back), or an older pf wrote the link.pf rprefreshes it. - unlinked: no id yet, or this machine has no record for it (a fresh clone).
pf rpcreates the record. - foreign:
pulpfixer.jsonnames a record that knows neither this path nor this remote, for example a copy or apulpfixer.jsontaken from another repo.pf rpasks 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:
- reads the repo’s own deploy notes (
AGENTS.md, README, docs) and the helper; - picks the dev-machine command and never a server-only one;
- writes the key you picked (
deploy,deploy:stagingordeploy:production; no terminal meansdeploy), with"message": truewhen the command commits and takes a commit message; - 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).