pf-cli — read, write and validate

pf-cli is the command-line frontend for the projectfile: it reads, writes and validates fields, resolves remote includes, and generates derived artifacts. It embeds the v1 JSON Schema for offline validation and is the canonical tool for editing projectfiles locally and in CI. Its extension namespace is org.projectfile.cli.

File and forge sync lives in pf-bridge, not here — pf-cli has no bridge, scan or forge commands. This page matches pf-cli --help exactly.

Release binary

Latest release 3.4.10. Published for 5 platforms: macOS, Linux.

base=https://kiota.ch/projectfile/cli/releases/download/v3.4.10curl --fail --location --output ~/.local/bin/pf-cli \    "$base/pf-cli-$(uname -s | tr A-Z a-z)-$(uname -m)"chmod +x ~/.local/bin/pf-cli

base=https://kiota.ch/projectfile/cli/releases/download/v3.4.10curl --fail --location --output ~/.local/bin/pf-cli \    "$base/pf-cli-$(uname -s | tr A-Z a-z)-$(uname -m)"chmod +x ~/.local/bin/pf-cli

Verify what you downloaded

Every binary ships a detached signature beside it. Confirm it with the maintainer's release key, which the keyserver serves:

gpg --keyserver hkps://keys.openpgp.org --recv-keys 8F89CBF7C8D51F8BEC7533C00925F8F79EBD3257curl --fail --location --output pf-cli.asc \    "https://kiota.ch/projectfile/cli/releases/download/v3.4.10/pf-cli-$(uname -s | tr A-Z a-z)-$(uname -m).asc"gpg --verify pf-cli.asc ~/.local/bin/pf-cli

Container image

Run the tool without installing it. The alias makes every command on this site work unchanged against your working directory:

ghcr.io/projectfile-org/cli — linux/amd64, linux/arm64, linux/riscv64

docker pull ghcr.io/projectfile-org/cli:3.4.10alias pf-cli='docker run --rm --user "$(id -u):$(id -g)" --group-add 0 \    --volume "$PWD:/app/ws" --workdir /app/ws ghcr.io/projectfile-org/cli:3.4.10 pf-cli'

damianbuho/projectfile-cli — linux/amd64

docker pull damianbuho/projectfile-cli:3.4.10alias pf-cli='docker run --rm --user "$(id -u):$(id -g)" --group-add 0 \    --volume "$PWD:/app/ws" --workdir /app/ws damianbuho/projectfile-cli:3.4.10 pf-cli'

kiota.ch/projectfile/cli — linux/amd64

docker pull kiota.ch/projectfile/cli:3.4.10alias pf-cli='docker run --rm --user "$(id -u):$(id -g)" --group-add 0 \    --volume "$PWD:/app/ws" --workdir /app/ws kiota.ch/projectfile/cli:3.4.10 pf-cli'

Stable releases also publish X.Y.Z, X.Y and X tags — pull the precision you want to pin.

Uninstall

rm -f ~/.local/bin/pf-cli          # release binarydocker image rm ghcr.io/projectfile-org/cli   # container image

The tool’s own listing, so a command added upstream appears here without a page edit; the sections below then cover the ones a project touches most.

13 commands — the listing pf-cli v3.4.10 reported when the page was built.

Read values out of the projectfile by path. Prints plain text, one value per line. Exits 3 when a path is missing, 2 when the invocation is wrong. With --suggest a missing path prints the nearest existing address instead.

pf-cli get <path>… [flags]

pf-cli get identity.namepf-cli get repositories[role=origin].urlpf-cli get identity.bogus --suggestpf-cli get repositories[].urlpf-cli get identity --format jsonpf-cli get org.projectfile.sinks.kiota.ref --scope org.projectfile.image

Replace the value at <path>. A bare value is stored as text, exactly as typed. Use --value-json or --csv for a typed value. Missing sections are created.

pf-cli set <path> [value] [flags]

pf-cli set license.spdx MITpf-cli set identity.version 1.10pf-cli set keywords --csv rust,wasmpf-cli set contacts --value-json '{"email":"a@example.com"}'

Append items to the list at <path>. Skips items that are already there.

pf-cli add <path> [value…] [flags]

pf-cli add keywords rust wasmpf-cli add repositories --field url=https://example.com/rpf-cli add keywords rust -n

Delete the value at <path>. Missing paths are not an error. Alias: delete.

pf-cli del <path> [flags]

pf-cli del keywords[0]pf-cli del keywords[99] --strict

Check that the projectfile is well-formed. Warns about repeated includes. Alias: lint.

pf-cli validate [directory] [flags]

pf-cli validatepf-cli validate /tmp/demopf-cli validate --strict-includes

Create a new projectfile.yaml (or .toml/.json) in [directory]. With pf-bridge installed this delegates to pf-bridge-init: full detection from sources (package.json, CITATION.cff, …) plus scanner gap-fill (git history, stack detection). Without it, a basic local scaffold prompts for namespace, name and title only — no scanners. Alias: scaffold.

pf-cli init [directory] [flags]

pf-cli initpf-cli init /tmp/demo --namespace org.example --name demo --non-interactive

Rewrite the projectfile from one format to another. Checks the result before writing; keeps the source file. Alias: conv.

pf-cli convert <from-format> <to-format> [directory] [flags]

pf-cli convert yaml tomlpf-cli convert yaml json --delete-sourcepf-cli convert toml yaml --force

Supported formats: toml, yaml (or yml), json.

Remove values your includes already provide. Keeps includes, $schema and spec_version. Alias: opt.

pf-cli optimize [directory] [flags]

pf-cli optimizepf-cli optimize --dry-run

Manage the includes list.

pf-cli includes [command]

Keep downloaded includes on disk for offline reads. Shared with pf-bridge and pf-ci.

pf-cli cache [command]

pf-cli cache statuspf-cli cache warm

Answer questions once; answers prefill future prompts. Enter accepts, Esc skips a section.

pf-cli setup [flags]

pf-cli setuppf-cli setup --format yaml

Personal defaults live at $XDG_CONFIG_HOME/projectfile/cli.{yaml,toml,json}. Fields set there (author name, ORCID, funding URLs, preferred format, …) pre-fill init prompts and renderer templates so the same flag is not repeated on every project.

Each failure class has its own code, so a script can tell a bad invocation from an absent field from an invalid document: