# CLI

> Install the Pullfrog CLI, and inspect and change repository settings, organization defaults, and stored credentials.

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.

```console
$ 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 write
```

Read, change or clear one value:

```bash
pullfrog config get model
pullfrog config set model anthropic/claude-opus
pullfrog config unset model
```

## Install and sign in

Install the CLI from npm, or run it with `npx` without installing:

**npm**:

```bash
npm install --global pullfrog@latest
```

**npx**:

```bash
npx pullfrog@latest config list
```

The CLI acts as the GitHub user signed in to the [GitHub CLI](https://cli.github.com). 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

```console
$ 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 tool
```

This page covers `config`, `secret` and `console`. The others have their own: [`run`](https://pullfrog.com/docs/prompts#from-the-terminal), [`auth`](https://pullfrog.com/docs/subscriptions), and [`watch` and `mcp`](https://pullfrog.com/docs/watch).

## Scope

Commands act on the repository in the current directory's GitHub `origin` unless you name a target:

```bash
pullfrog config get model --repo acme/api
pullfrog config set model openai/gpt-sol --org acme
pullfrog config set enabled false --repo acme/api
```

The `--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

```bash
pullfrog config keys
pullfrog config keys review
pullfrog config keys --org acme
pullfrog config describe shell
```

The `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](https://pullfrog.com/docs/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

```bash
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.review
```

Use `--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 `push` or `shell`, 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.

```bash
pullfrog config set enabled false --repo acme/api --yes
pullfrog config set auto-merge true --yes --ack-auto-merge
```

The `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

```bash
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 --yes
```

These 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 `--file` option takes one name at a time.

Subscription credentials have their own commands:

```bash
pullfrog auth codex --org acme
pullfrog auth claude --repo acme/api
pullfrog auth grok --org acme
```

A 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](https://pullfrog.com/docs/permissions#roles).
- Your GitHub token must also reach the target, and a suspended installation cannot be configured.

## Console

```bash
pullfrog console
pullfrog console --org acme
pullfrog console --repo acme/api
pullfrog console --no-browser
```

The 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.

```bash
npm install --global pullfrog@latest
```

Restart 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.
