Español · Українська

Projectfile CLI

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.

Features

• Document read, write and query

See Features for the full list.

What this provides

• Executable pf-cli — command pf-cli
• Container image ghcr.io/projectfile-org/cli:latest
• Container image damianbuho/projectfile-cli:latest

Installation

Container image

Pull the published container image:

Pull from GHCR — linux/amd64, linux/arm64, linux/riscv64

docker pull ghcr.io/projectfile-org/cli:latest
alias 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:latest pf-cli'

Pull from DockerHub — linux/amd64

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

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

If the registries above are unreachable, pull from the origin instead:

Pull from Kiota — linux/amd64

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

Then run it as if it were installed — the alias runs every example as written against the current directory:

pf-cli --help

Prebuilt binary

Download the prebuilt binary for your platform from GitHub Releases:

mkdir -p ~/.local/bin
curl --fail --location --output ~/.local/bin/pf-cli https://github.com/projectfile-org/cli/releases/latest/download/pf-cli-$(uname -s | tr A-Z a-z)-$(uname -m)
chmod +x ~/.local/bin/pf-cli
~/.local/bin/pf-cli --help

Published for: linux/amd64, linux/arm64, linux/riscv64, darwin/amd64, darwin/arm64

Usage

pf-cli

$ pf-cli --help
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.

File and forge sync (bridge, forge, scan): use pf-bridge.

Usage:
  pf-cli [command]

Examples:
  pf-cli init --namespace org.example --name demo
  pf-cli get identity.name
  pf-cli set license.spdx MIT
  pf-cli add keywords rust wasm
  pf-cli del keywords[0]
  pf-cli validate
  pf-cli convert yaml toml
  pf-cli optimize
  pf-cli cache status

Read:
  get         Read one or more projectfile fields

Write:
  add         Append items to a projectfile list
  del         Remove a field, list item, or map entry from projectfile
  set         Write a value into a projectfile field

Validate:
  validate    Validate a projectfile against the v1 JSON Schema

Maintain:
  cache       Manage pf-cli’s local cache for offline use
  convert     Convert a projectfile between encodings (toml/yaml/json)
  includes    Manage the includes list
  init        Scaffold a new projectfile document
  optimize    Remove local fields that duplicate include values
  setup       Edit your per-user configuration interactively

Other:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command

Common flags:
    -q, --quiet          mute info; warnings and errors still print
  -v, --verbose        show each step; also PF_CLI_VERBOSE=1
  --offline            refuse network; use cache and embedded data

Flags:
      --colors string        colour output: auto|always|never; also PF_CLI_NO_COLOR=1 (default "auto")
      --fail-on string       abort includes at error|warning (default "error")
  -h, --help                 help for pf-cli
      --ignore-user-config   skip $XDG_CONFIG_HOME/projectfile/cli.* loading
      --offline              refuse network; use cache and embedded data
  -q, --quiet                mute info; warnings and errors still print
      --sorted               write YAML keys in sorted order
      --timeout duration     per-attempt network timeout (default 10s)
  -v, --verbose              show each step; also PF_CLI_VERBOSE=1
  -V, --version              print the version

Documentation:
  https://github.com/projectfile-org/cli/tree/main/docs

Report a bug:
  https://github.com/projectfile-org/cli/issues

Use "pf-cli [command] --help" for more information about a command.

Examples and every command’s help are in Usage.

Building

Clone the repository with its submodules:

git clone --recurse-submodules https://codeberg.org/projectfile/cli cli && cd cli

Build the container image locally:

make container-build

• Makefile reference

Run make with no arguments for the default target; run make help to list every target.

For the local dev loop, make dev-container brings up the dev-container.

Pipeline entry points:

• make analyzed — Run the heavy analysis sweep (mutation testing, benchmarks)
• make audited — Re-scan the pinned dependencies and published artifacts for new vulnerabilities
• make check-outdated — Report every pinned dependency that lags upstream
• make ready-to-publish — Run the pseudo-CI pipeline locally — build, test and scan, without publishing

Documentation

• Configuration

Policies

• How to contribute
• Security policy
• Getting support
• Code of Conduct
• AI and LLM Policy

Links

• Projectfile Specification

License

This project is licensed under MIT — see the LICENSE file for details.