pf

A command-line tool for Project Feed. Manage your projects, tasks, posts, and more without leaving the terminal.

Install

npm install -g pfeed-cli

Or run directly with npx:

npx pfeed-cli projects list

Setup

You'll need an API key from your Project Feed workspace settings.

pf auth login

This will prompt you for your key and store it locally. You can also set it as an environment variable:

export PROJECT_FEED_API_KEY=pf_live_your_key_here

Or jump straight in with the guided setup:

pf quickstart

Usage

pf follows the same resource action pattern as the GitHub CLI:

pf projects list
pf tasks create --title "Fix login bug" --project <id> --priority high
pf posts view 3                          # by post number
pf notifications unread-count

Quick overview

| Command | What it does | |---------|-------------| | pf projects list | List all projects (use --show-archived to include archived) | | pf projects create | Create a new project (interactive) | | pf tasks list --status in_progress | List tasks filtered by status | | pf tasks create | Create a task (interactive or with flags) | | pf tasks view 5 | View a task by number (or by ID) | | pf posts list --project <id> | List posts for a project | | pf posts publish 3 | Publish a draft post by number | | pf comments add 2 --content "looks good" | Comment on a post by number | | pf reactions toggle 1 🚀 | Toggle a reaction on a post by number | | pf media list --post <id> | List media on a post | | pf notifications mark-all-read | Clear your notifications | | pf status | Dashboard with project/task summary | | pf init | Scaffold a new project in the current directory | | pf open WR-42 --task | Open a task by identifier in the browser | | pf history | See recent actions | | pf undo | Reverse your last edit or create |

Every command supports --json for machine-readable output:

pf tasks list --json
pf tasks list --json id,title,status    # specific fields only

You can also pipe JSON through a jq-like filter:

pf posts list --json --jq ".[].title"

Sorting and filtering

List commands accept --sort and --reverse:

pf tasks list --sort priority --reverse
pf posts list --sort title

Dry runs

Destructive commands (delete, archive, mark-all-read, etc.) support --dry-run to preview what would happen without making changes:

pf posts delete <id> --dry-run
pf projects archive <id> --dry-run

Interactive selection

When you run a view or edit command in a terminal without specifying an ID, you'll get an interactive picker:

pf tasks view       # pick from a list
pf posts edit       # pick, then edit

History and undo

Every create and edit is logged locally. You can review recent actions and reverse the last one:

pf history
pf undo

Undo works by restoring the previous state for edits, or deleting the resource for creates. Deletes cannot be undone.

Directory linking

You can associate a directory with a project so you don't have to pass --project every time:

pf link <slug>          # link by project slug
pf link <projectId>     # or by ID — creates .pf/config.json in the current directory
pf unlink               # removes it

When linked, commands like pf tasks list will default to that project. New links also save the workspace slug when the API exposes it, so pf workspace members can work without a global defaultWorkspace.

Workspace discovery

pf workspace list       # show workspaces available to the API key
pf workspace current    # show the workspace resolved from flags/env/link/config
pf workspace members    # list members using the resolved workspace

Raw API access

For anything the CLI doesn't cover, you can hit the API directly with your auth injected:

pf api GET /projects
pf api POST /posts --data '{"title": "Hello", "projectId": "..."}'

Command aliases

Most commands have short aliases so you can type less:

pf p   -> pf projects
pf t   -> pf tasks
pf po  -> pf posts
pf c   -> pf comments
pf r   -> pf reactions
pf n   -> pf notifications
pf ws  -> pf workspace
pf wh  -> pf webhooks

Subcommands have aliases too: ls for list, rm for delete, show for view.

Shell completions

Generate completion scripts for your shell:

eval "$(pf completion bash)"    # bash
pf completion zsh > ~/.zfunc/_pf  # zsh
pf completion fish | source     # fish

Configuration

Config is stored at ~/.config/project-feed/config.json (Linux/macOS) or %APPDATA%/project-feed/Config/config.json (Windows).

pf config set defaultProject <id>     # skip --project on every command
pf config set defaultWorkspace <slug>
pf config list                        # see current config
pf config path                        # show config file location

API keys and default projects can also be scoped to a workspace inside the active profile:

pf auth login --workspace engineering
pf config set apiKey pf_live_... --workspace engineering
pf config set defaultProject <id> --workspace engineering
pf config get defaultProject --workspace engineering

When --workspace <slug> is provided, workspace values override the active profile's global apiKey and defaultProject. defaultWorkspace remains a global profile setting.

Every request sends an X-Project-Feed-Client header identifying the caller (defaults to cli). Override it with the PFEED_CLIENT environment variable (PROJECT_FEED_CLIENT also works), or set it per profile:

export PFEED_CLIENT=claude   # e.g. when pf is driven by Claude
pf config set client claude  # persists the override in the active profile

Profiles

You can create multiple config profiles for different workspaces or accounts:

pf config profile create work
pf config profile use work
pf config set apiKey pf_live_...
pf config profile use default       # switch back
pf config profile list

Or use a profile for a single command with --profile:

pf projects list --profile work

Global flags

These work on any command:

--json [fields]     Output as JSON, optionally selecting specific fields
--jq <expr>         Filter JSON output with a path expression
--verbose           Show HTTP request/response details
--debug             Show full request/response bodies
--sort <field>      Sort list output by a field
--reverse           Reverse sort order
--profile <name>    Use a specific config profile
--api-key <key>     Use a different API key for this command
--project <id>      Override the default project
--workspace <slug>  Assert the workspace slug for workspace-scoped API calls
--no-color          Disable colored output

All commands

Run pf --help or pf <command> --help for full details.

auth - login, logout, status, check config - set, get, list, path, profile projects - list, create, view, edit, archive tasks - list, create, view, edit, comment, link, unlink checklist (cl) - list, add, check, uncheck, edit, delete subtasks (st) - list, add tags - list, add, remove, set posts - list, create, view, edit, delete, publish, unpublish comments - list, add, edit, delete reactions (r) - list, toggle media - list, upload, view, delete canvases (cv) - list, create, view, edit, archive, delete spaces - list docs - list, view, create, edit, set-content, versions, restore-version, archive, delete me - view, edit, orgs, api-keys, push-subscriptions limits - show API rate-limit quota and version info domains - check-dns, verify audit-logs (audit) - export the audit log (json/cef/csv) notifications - list, unread-count, mark-read, mark-all-read, preferences workspace - list, current, members webhooks - list, create, view, edit, delete, test, regen-secret, deliveries, retry, listen status - dashboard overview history - recent action log undo - reverse last create or edit init - scaffold a new project open - open a resource in the browser (--post, --task for identifier URLs) link / unlink - associate a directory with a project quickstart - guided onboarding api - raw API access completion - shell completion scripts

Releases

Pushing to main triggers CI. If the version in package.json is newer than what's on npm, it publishes automatically.

npm publishing uses Trusted Publishing (OIDC). There's no npm token stored in GitHub secrets. Instead, the GitHub Actions workflow exchanges a short-lived OIDC token directly with npm. You set this up by linking the repo to the package on npmjs.com under Settings > Publishing access > Add linked repository.

The workflow also creates a GitHub Release with auto-generated notes.

Requirements

Node.js 20 or later.

License

MIT