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
| Field | Meaning |
|---|---|
run | The shell line to run |
description | Shown in the menu and by pf list |
group | The menu heading |
cwd | Directory to run in, relative to the repo root |
message | true 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) |
icon | A codicon name (database, cloud-upload) for the command’s button, see pf actions |
featured | true 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.