Skip to Content
Conceptspulpfixer.json

pulpfixer.json

pulpfixer.json sits at the root of a repo. It overrides detection, adds commands to the menu, and names the repo’s profile. pf init writes a starting file from what pf detected.

Older pf versions called it pf.json. pf still reads a pf.json when the repo has no pulpfixer.json, and pf rp (or pf init) renames it; the content is unchanged. When both files exist, pf reads only pulpfixer.json.

{ "name": "my-service", "commands": { "dev": { "run": "uv run fastapi dev", "description": "Run the API", "group": "Develop" }, "seed": { "run": "./scripts/seed.sh", "description": "Load sample data", "group": "Tools", "cwd": "." } } }

Commands

FieldMeaning
runThe shell line to run
descriptionShown in the menu and by pf list
groupThe menu heading
cwdDirectory to run in, relative to the repo root
messagetrue when the command makes a commit and takes a commit message as its last argument, so pf d "text" passes it on (deploy entries only)
iconA codicon  name (database, cloud-upload) for the command’s button, see pf actions
featuredtrue to show the command as a button on the Background Tone card. Custom commands are not featured unless they say so

Built-in names (dev, build, test, lint, install) override detection. deploy:staging, deploy:production, publish:staging and doc override those commands. A plain deploy entry is the repo’s own deploy when it names no environment: pf deploy (pf d) runs it when there is no staging or production target, and always asks first, like production. Any other name shows up in the menu and runs with pf <name>, for example pf seed.

actions

{ "commands": { "seed": { "run": "./scripts/seed.sh", "icon": "database", "featured": true } }, "actions": { "install": { "featured": false }, "build": { "featured": true, "icon": "package" } } }

Overrides for the repo’s buttons by action id (dev, deploy:staging, publish:staging, doc, build, install:local, a custom command’s name, …). featured shows or hides the button, icon is a codicon name. They beat a custom command’s own icon / featured, which beat the defaults. pf actions --all lists the ids; pf actions feature <id> and unfeature <id> write this section. A bad icon name is ignored.

id

{ "id": "my-service-3f9a2c1b", "name": "my-service" }

id links the repo to pf’s own record of it, ~/.pf/repos/<id>.json on your machine. pf keeps the things that should stay out of the repo there: the checkouts it has seen, the git remote, and private per-repo settings such as security-related ones. pf rp writes the id (the repo name plus a random suffix) and the record. Because the id travels with the repo, the record survives a moved checkout or a renamed remote. Commit the id and do not edit it by hand. See pf repo.

Profile and agent limits

{ "profile": "acme", "agent": { "aws": { "scopes": ["identity", "ecs"] } } }

profile names one of your user profiles. agent.aws may only narrow what that profile allows, never widen it, because a cloned repo is not trusted. See Profiles.

bgTone

{ "bgTone": { "color": "#3b82f6", "logo": "assets/logo.svg" } }

The settings of the Background Tone extension: the window tint and the repo logo. The extension reads and writes this section (committed with the repo), and pf rp sets logo from an image it finds in the repo. pf does not interpret the other keys.

Production

A deploy:production entry is one of the three ways a repo can define production (with a script or the repo’s own CLI). pf never guesses it. See Deploy and publish.

Last updated on