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.
Install and sign in
Install the CLI from npm, or run it withnpx without installing:
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.
Scope
Commands act on the repository in the current directory’s GitHuborigin unless you name a target:
--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
keys and describe commands work offline and describe what the installed CLI supports, not what you may change. The list command shows the source of each value and whether you can write it.
The
hooks.stop key is accepted and stored, but Pullfrog does not currently run a stop hook.
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
--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.
--yes. Enabling auto-merge also needs --ack-auto-merge, or typing MERGE at the prompt. A confirmation never grants a permission you lack.
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
- 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.
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
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. See Permissions for the full role table.
Console
CLI compatibility
The API rejects a CLI whose contract version it does not support, before it does anything. Releases that keep the contract keep working; you upgrade only when it changes, and older clients that send no contract version are rejected. To upgrade, runnpm install --global pullfrog@latest, then restart any running pullfrog watch or MCP process.
If the latest CLI still reports an incompatibility, the matching server deployment has not finished yet. Retry once it has.