App Command Validation

Updated on Oct 5, 2026

frg app commands run across the repositories listed in application.toml. How Forge validates inputs depends on the command's execution mode. This page explains both modes and how to fix validation failures.

Prerequisites

An .forge/config/application.toml that lists your repositories. To populate it, run frg app discover. See Multi-Repository Application Commands.
A configured AI agent. App execution requires agent configuration (agents.toml).

Execution modes

Mode	Commands	Validation
Direct execution	All other `frg app` operations, for example `frg app issue draft`, `frg app issue split`, `frg app code review`	Forge validates inputs at the application level before the agent runs.
Workflow execution	`frg app issue plan`, `frg app code create`, `frg app pr draft`, `frg app pr publish`, `frg app pr review`, `frg app pr merge`	Forge skips app-level validation. Each child repository's workflow validates its own inputs.

The help for workflow-execution commands says: NOTE: This command uses workflow execution mode. It will execute the configured workflow in each child repository.

The built-in workflows are:

Command	Workflow
`frg app issue plan`	`issue-to-plan`
`frg app code create`	`code-to-review`
`frg app pr draft`, `frg app pr publish`	`pr-create-publish`
`frg app pr review`, `frg app pr merge`	`pr-review-merge`

The mode is set by the app_workflow setting in commands.toml.

Direct execution validation

A direct-execution command runs once, with context from all repositories. Before it starts the agent, Forge:

Extracts the required input files from the operation's task prompt.
Checks them in the application's job directory.
Stops before any work begins if a required file is missing.

frg app code review is a special case. It checks the task list, code/tasks.md, in each child repository's job directory, for example .forge/work/job_42/code/tasks.md.

When validation fails, the command stops with:

text

Error: App command cannot proceed: required input files are missing

Generative commands, such as frg app issue draft, have no required inputs.

Workflow execution

A workflow-execution command runs frg workflow run for the mapped workflow in each child repository. The app layer doesn't validate inputs, so errors come from the individual workflow steps, the same as in a single repository.

Example output (abbreviated):

text

Multi-Repository Workflow: code-to-review (Issue #866)
Max Workers: 3 | Repositories: 3
Press Ctrl+C to cancel
...
2 succeeded, 1 failed

Workflow-execution commands accept a smaller set of options:

Option	Description
`--start-from <STEP_NAME>`	Start workflow execution from a specific step instead of the initial state
`--bypass-approvals`	Skip approval gates (for CI/automation)
`--dry-run`	Validate workflow without executing

They don't support --clear. For the full option list per command, see the Command Reference.

Troubleshooting

App command cannot proceed: required input files are missing

Cause: A direct-execution command needs a file that doesn't exist in one or more repositories. For frg app code review, this is usually code/tasks.md.

Solution:

Read the output to find the repository and file that failed.
Generate the missing files. For frg app code review, create the implementation plan in every repository:

bash

frg app issue plan

Check that the file exists in each child repository, for example .forge/work/job_42/code/tasks.md.
Run the app command again.

Note: The binary may suggest Run 'frg app code plan' first to generate tasks. There is no frg app code plan command. Use frg app issue plan instead.

No valid repositories available. Check application.toml and ensure repositories exist with correct allow_app UUID.

Cause: application.toml has no reachable repositories, or no repository's project.toml has an allow_app value matching the application UUID.

Solution:

Add allow_app = "<application UUID>" to each child repository's project.toml.
Discover the repositories:

bash

frg app discover

To replace the existing list, run frg app discover --force.
To generate project.toml for child repositories that don't have one, run frg app discover --auto. In CI, set FORGE_ACCEPT_AUTO_RISK=true to skip the AI-generated content warning.

The --clear flag is not supported for frg app ...

Cause: You passed --clear to a workflow-execution command. The full message explains that it uses stateful workflow execution, and context is managed within each child repository independently.

Solution:

Remove --clear from the app command.
To reset a session, run the single-repository command with --clear in the affected child repository.

A workflow step fails on missing inputs

Cause: In workflow execution, each step validates its own inputs. A previous step didn't complete in that repository.

Solution:

Read the failing step's error message for that repository.
Check that the earlier steps succeeded, for example with frg workflow status.
Resume from the failed step:

bash

frg app code create --start-from <STEP_NAME>