CLI

pfai is the command-line client for ProxifAI. It talks to the same API your browser uses, so anything you can click in the web UI you can script — managing tasks and projects, browsing repos and pull requests, dispatching agents, running pipelines, configuring providers, and more. The CLI is built on Cobra and follows kubectl-style verbs (list/ls, view/get, delete/rm) with structured output (table, JSON, YAML) for easy piping.

Install

pfai is published as a single static binary on the proxifai-oss releases page for macOS and Linux on both amd64 and arm64.

# Pick the right asset for your OS/arch from the latest release.
# Example for macOS arm64:
curl -L -o pfai \
  https://github.com/proxifai/proxifai-oss/releases/latest/download/pfai-darwin-arm64
chmod +x pfai
sudo mv pfai /usr/local/bin/
pfai version

git clone https://github.com/proxifai/proxifai-oss.git
cd proxifai-oss
go install ./cmd/pfai
# Or, for a tagged release without a clone:
go install github.com/proxifai/proxifai-oss/cmd/pfai@latest

Verify the install:

pfai version
pfai auth ping --server https://your-proxifai-host

Authenticate

pfai auth login runs a PKCE OAuth flow: it spins up a tiny local callback server, opens your browser to the workspace’s authorization endpoint (Keycloak by default), exchanges the code for a long-lived pfai token, and writes it to ~/.proxifai/credentials.json.

pfai auth login                            # opens a browser
pfai auth login --no-browser               # prints the URL instead
pfai auth login --as work                  # save under a named context
pfai auth status                           # who am I, and is my token valid
pfai auth token                            # decode the active token's JWT claims
pfai auth ping                             # health-check the server
pfai auth logout                           # clear stored credentials

For non-interactive environments (CI, scripts) you have three options:

PFAI_EXECUTION_ID is set automatically inside agent containers by the workflow runtime, so commands like pfai exec status work without extra wiring.

Contexts

A context bundles a server URL + token + identity under a name. Switch between them without re-logging in:

pfai context ls                # all configured contexts
pfai context current           # active context name
pfai context use prod          # make 'prod' the active context
pfai context add staging --server https://staging.example.com --token …
pfai context rm old-prod       # delete a context
pfai --context staging task ls # one-shot override (also -C)

The active context lives in ~/.proxifai/contexts.yaml; the canonical credentials file remains ~/.proxifai/credentials.json.

Global flags

Every command accepts these:

Output format precedence: -o flag → --json → context’s saved format → table.

Output formats

pfai task ls                           # human-readable table (default)
pfai task ls -o json                   # full JSON, one record per row
pfai task ls -o yaml                   # YAML for piping into kustomize/etc.
pfai task ls -o name                   # IDs only, one per line — pipe to xargs
pfai task ls --json -q '[?priority==`high`].id'   # JMESPath filter

The name format is built for shell composition:

# Cancel every running pipeline:
pfai pipeline ls --status running -o name | xargs -n1 pfai pipeline cancel

Verb aliases

Every CRUD subcommand has both forms — pick whichever your fingers prefer:

So pfai task list, pfai task ls, and pfai task get <id> all work.

Command reference

60 top-level commands organized into 6 Cobra groups, plus a handful of utilities. Run pfai <command> --help for full subcommand docs.

Core

Code

Cloud

Platform

Collaboration

Admin

Utility

Examples

# Triage: list high-priority open tasks assigned to me, JSON to jq
pfai task ls --status open --priority high --assignee @me --json | jq '.'

# Open the first PR I haven't reviewed in my browser
pfai pr ls --review-requested @me -o name | head -1 | xargs pfai pr view --web

# Dispatch a task to an agent
pfai task dispatch task_42 --agent claude-code --branch main

# Watch a pipeline run to completion, then exit non-zero if it failed
pfai pipeline rerun run_123
pfai wait pipeline-run/run_123

# Tail logs for the latest workflow execution
pfai workflow executions --latest -o name | xargs pfai logs

# Drive a workflow from a script
pfai workflow run wf_42 --param key=value
pfai workflow logs $(pfai workflow executions wf_42 --latest -o name)

# Bulk update labels: add 'needs-review' to all PRs older than 3 days
pfai pr ls --updated-before "3 days ago" -o name | \
  xargs -I{} pfai pr update {} --add-label needs-review

# Direct API for an endpoint without a wrapper:
pfai api GET /api/v1/forge/repos
pfai api POST /api/v1/forge/repos '{"name":"new-repo","private":true}'

Shell completion

# bash
pfai completion bash > ~/.local/share/bash-completion/completions/pfai

# zsh (with oh-my-zsh-style fpath)
pfai completion zsh > "${fpath[1]}/_pfai"

# fish
pfai completion fish > ~/.config/fish/completions/pfai.fish

Completion includes context names for pfai context use / --context and resource IDs for verbs that take them.

Environment variables

See also