Flags
Flags are double-dash shortcuts you can put in any instruction Pullfrog reads. Built-in flags change how a run behaves, and custom flags expand into text you define.
@pullfrog fix the flaky checkout test --opus --timeout=2hWhere flags are read
Pullfrog assembles each run's instructions from these levels, most general first:
- Org standing instructions — every repository in the organization
- Repo standing instructions — every run in the repository
- Mentions instructions — runs started by an
@pullfrogmention - The per-run request — your
@pullfrogprompt, or the triggering automation's instructions when you did not tag Pullfrog
The standing levels are always added to the run. The per-run level is one or the other: when you tag @pullfrog, your prompt is the request and the automation's instructions do not apply.
Flags resolve when Pullfrog starts a run from a GitHub event. A custom workflow that passes a raw prompt skips this resolution, so configure it with the action's inputs.
Custom flags (aliases)
A custom flag is a text alias: define --refactor once, and every occurrence expands in place to its replacement text. Use one for any snippet you repeat, such as a refactoring checklist or a review rubric.
--mini → --model=anthropic/claude-haiku
--ship → --opus --notimeoutAliases expand before built-in flags resolve, so an alias can contain built-in flags: @pullfrog fix the flaky test --ship runs on Claude Opus with no timeout. Expansion is a single pass, so an alias inside an alias's text is not expanded again.
To create one:
- Open Agent → Flags in a repository's console. For an organization-wide flag, open the organization console and expand Advanced.
- Click Add flag, enter the Flag name without the dashes, such as
refactor, and enter the Replacement text.
A repo flag shadows an org flag with the same name. A flag name starts with a letter and contains letters, digits, underscores, and hyphens. Names are case-sensitive, so --refactor and --Refactor are different flags.
Precedence
Built-in flags resolve last-occurrence-wins across all levels. Reading org, then repo, then the per-run request, the last value of a flag wins, so a more specific level overrides a more general one:
org --timeout=2h
repo --timeout=30m
user --notimeout ← wins: this run has no timeoutPullfrog removes built-in flags from the text before the agent sees it.
Built-in flags
| Flag | Effect |
|---|---|
| Model flags | Pick the model for one run |
--timeout, --notimeout | Change or remove the run timeout |
--debug | Raise the run's logging |
--effort | Set reasoning effort |
--xrepo | Let the run reach other repositories in the organization |
Model
A model flag overrides the model for one run. Family flags resolve to the latest version of that model, on the repository's current provider when that provider carries it:
| Flag | Model |
|---|---|
--opus / --sonnet / --haiku | Claude Opus / Sonnet / Haiku |
--fable | Claude Fable (limited availability; needs Anthropic Fable access) |
--gpt / --codex | GPT Sol |
--gpt-pro / --gpt-mini | GPT Sol Pro / Luna |
--sol / --terra / --luna | GPT Sol / Terra / Luna |
--gemini / --gemini-flash | Gemini Pro / Flash |
--grok | Grok |
--kimi / --kimi-k3 | Kimi K2 / K3 |
--deepseek / --deepseek-flash | DeepSeek Pro / Flash |
--minimax | MiniMax M2.5 |
--glm | GLM |
--model=<slug> | Any model slug, for example --model=openrouter/claude-opus |
Where a model flag is written decides how the run treats it:
- A model flag in your own
@pullfrogprompt is an explicit request. When no provider key is configured, the OSS subsidy does not fund the model, or Pullfrog Router cannot serve it, the run fails before the agent starts with an error that names the fix. - A model flag in org, repo, or automation instructions is a standing default, and the run treats it like the repository's own model setting.
- A
--model=slug that Pullfrog does not recognize is left in the prompt as plain text.
Timeout
| Flag | Effect |
|---|---|
--timeout=<duration> | Set the run timeout, for example --timeout=30m or --timeout=1h30m |
--notimeout | Remove the timeout |
The default is 1 hour. A timeout input on the workflow step takes precedence over these flags.
Debug
| Flag | Effect |
|---|---|
--debug | Raise this run's logging so the workflow log shows what the agent and its harness did |
Use it when a run fails with nothing useful in the log. The log then records Pullfrog's debug output and each request to your model provider. The flag changes only what the run logs, never what the agent may do, and applies only to the run you put it on.
The workflow input does the same for every run of that workflow:
- uses: pullfrog/pullfrog@v0
with:
debug: enabledEffort
| Flag | Effect |
|---|---|
--effort=<level> | Set reasoning effort: low, medium, high, xhigh, max, or a position from 0 to 1 such as 0.75 |
Higher effort reasons longer and costs more; lower effort finishes faster. Models name and count their levels differently, so --effort sets a position on the running model's own range: low is its lowest level and max its highest. A level between two of the model's levels rounds down. The repository's effort setting is the default.
Like every built-in flag, --effort=medium in repo instructions is a standing default that a per-run --effort=max overrides. An alias can wrap it:
--deep → --effort=max
