CLI
The pullfrog CLI reads and writes the same settings as the console, from a terminal or a script. Each value shows where it comes from: the repository, the organization default, or Pullfrog's default.
$ pullfrog config list --repo pullfrog/scratch
pullfrog/scratch
enabled true [repo]
model "openai/gpt-sol" [org]
effort 0.5 [default]
push "enabled" [repo]
shell "restricted" [repo]
review.mode "agent" [repo]
review.re-review true [repo]
issue.mode "links" [repo]
# ...
$ pullfrog config describe review.mode
review.mode
behavior when a PR is opened
values: none | links | agent
unset: not allowed
write access: repo writeRead, change or clear one value:
pullfrog config get model
pullfrog config set model anthropic/claude-opus
pullfrog config unset modelInstall and sign in
Install the CLI from npm, or run it with npx without installing:
npm install --global pullfrog@latestnpx pullfrog@latest config listThe CLI acts as the GitHub user signed in to the GitHub CLI. Run gh auth login once; the CLI then sends whatever gh auth token prints, which is GH_TOKEN or GITHUB_TOKEN when either is set. The token needs the repo and read:org scopes, which gh auth login requests by default.
Commands
$ pullfrog --help
usage: pullfrog <command>
commands:
config inspect and change repository or organization settings
console open the repository or organization console
secret list secret names, save or delete scoped credentials
init install pullfrog on the current repository and open its dashboard
run start a run from a prompt, like the console's prompt box
auth manage provider credentials for the current repository
watch stream a PR's activity as one JSON line per event
mcp run a stdio MCP server exposing PR activity as an agent toolThis page covers config, secret and console. The others have their own: run, auth, and watch and mcp.
Scope
Commands act on the repository in the current directory's GitHub origin unless you name a target:
pullfrog config get model --repo acme/api
pullfrog config set model openai/gpt-sol --org acme
pullfrog config set enabled false --repo acme/apiThe --repo option (alias -R) selects one repository. The --org option selects organization defaults, or a personal account's shared settings. You cannot combine them.
Disabling a repository affects that repository only. Re-enabling it does not install a missing workflow; run pullfrog init for setup.
Keys and values
pullfrog config keys
pullfrog config keys review
pullfrog config keys --org acme
pullfrog config describe shellThe keys and describe commands work offline and describe what the installed CLI supports. The list command shows the source of each value and whether you can write it.
| Repository keys | Values |
|---|---|
enabled, progress-comments, oss, signed-commits, auto-merge | true or false |
model | provider/model, or unset |
effort | Number from 0 to 1, or unset |
instructions, env-allowlist | Text, or unset |
push, shell | disabled, restricted, enabled |
hooks.setup, hooks.post-checkout, hooks.pre-push, hooks.stop | Script text, or unset |
prompts.review, prompts.build, prompts.plan, prompts.address-reviews, prompts.fix-ci | Text, or unset |
mention.enabled, mention.non-collaborators | true or false |
mention.instructions | Text, or unset |
review.mode | none, links, agent |
review.non-collaborators, review.re-review, review.approve, review.drafts, review.own-prs, review.status-check, review.approval-check | true or false |
issue.mode | none, links, plan, build, custom |
issue.instructions, label.instructions | Text, or unset |
issue.non-collaborators, label.enabled, address-reviews.enabled, fix-ci.own-prs, fix-ci.reviewed-prs | true or false |
The hooks.stop key is accepted and stored, but Pullfrog does not currently run a stop hook.
| Organization keys | Values |
|---|---|
model, effort, instructions | Same types as the repository keys |
xrepo.brief | Text, or unset |
billing.mode | byok, router |
billing.auto-reload | true or false |
billing.reload-threshold-usd | Whole USD, 5–10000 |
billing.reload-amount-usd | Whole USD, 10–100000 |
billing.monthly-limit-usd | Whole USD, 10–1000000, or unset for unlimited |
billing.limit-mode | hard_cap, alert_only |
Inherited defaults
When a repository has no model or effort of its own, get prints the organization default. With neither set, model prints auto and effort prints 0.5.
- Unsetting a repository value restores inheritance.
- These are configured defaults, not a prediction of the next run. Flags, workflow inputs, credentials and funding can all change what runs.
- Outside collaborators cannot read private organization defaults, so an inherited value shows as unavailable to them.
Text and scripts
pullfrog config set instructions --file instructions.md
pullfrog config set hooks.setup --file setup.sh
pullfrog config set prompts.review 'Check authorization boundaries.'
pullfrog config unset prompts.reviewUse --file - to read from stdin. Each prompt key changes only that prompt. The environment allowlist takes one variable name per line.
Confirmations
These changes ask for confirmation before they are written:
- Disabling a repository or its OSS funding.
- Widening
pushorshell, or adding names to the environment allowlist. - Allowing non-collaborators, or letting reviews approve.
- Enabling auto-merge.
- Raising automatic charges: switching to Router billing, enabling auto-reload, raising a billing amount, removing the monthly limit, or choosing
alert_only.
Without a terminal, pass --yes. Enabling auto-merge also needs --ack-auto-merge, or typing MERGE at the prompt. A confirmation never grants a permission you lack.
pullfrog config set enabled false --repo acme/api --yes
pullfrog config set auto-merge true --yes --ack-auto-mergeThe oss key turns an existing funding grant on or off; it does not enroll a repository. Turning a grant on can clear an incompatible model, and the CLI reports it. Signed commits and auto-merge still depend on the plan and on runtime checks.
Secrets
pullfrog secret list
pullfrog secret list --org acme
pullfrog secret set OPENAI_API_KEY --org acme
pullfrog secret set SERVICE_TOKEN --file ./token --repo acme/api
pullfrog secret delete SERVICE_TOKEN --repo acme/api --yesThese commands manage Pullfrog's secret store, not GitHub Actions secrets.
- The list shows names only, including organization secrets a repository inherits. Values are never returned.
- A repository secret overrides an organization secret of the same name. Deleting the repository copy exposes the organization value again.
- Setting a secret prompts for a masked value, or reads it from
--file PATH(-for stdin). Values are never accepted as arguments. - Several names in one command prompt for each value and save together, which suits custom provider credentials. The
--fileoption takes one name at a time.
Subscription credentials have their own commands:
pullfrog auth codex --org acme
pullfrog auth claude --repo acme/api
pullfrog auth grok --org acmeA repository copy of a subscription credential takes precedence over the organization one. Saving one for an organization therefore stops if any repository has its own copy, prints the secret delete command for each, and saves nothing. Run those, then run it again. The secret set command refuses these three credentials for the same reason; a plain API key has no such restriction.
Permissions
| Change | Required access |
|---|---|
| Ordinary repository settings | Repo write |
| Push, shell, environment allowlist, signing, auto-merge, OSS funding | Repo admin |
| Repository secrets | Repo admin |
| Organization defaults and instructions | Org member |
| Billing settings and organization secrets | Org owner |
Three more rules apply:
- Reading a repository's settings or secret names also needs repo write, since anyone can read a public repository.
- On a personal account the owner has the organization-owner permissions.
- Your GitHub token must also reach the target, and a suspended installation cannot be configured.
Console
pullfrog console
pullfrog console --org acme
pullfrog console --repo acme/api
pullfrog console --no-browserThe command prints the console URL and opens it when stdout is a terminal. Use the console for payment methods, subscriptions, advanced trigger overrides, learnings and custom flags. Configuration has no bulk apply, export or JSON output.
CLI compatibility
The API rejects a CLI whose contract version it does not support, before it does anything. A client that sends no contract version is rejected too.
npm install --global pullfrog@latestRestart any running pullfrog watch or MCP process after an upgrade. If the latest CLI still reports an incompatibility, the matching server deployment has not finished yet, so retry once it has.

