Command Structure

Updated on Oct 5, 2026

This page explains how frg commands are organized. It covers command groups, shared flags, execution context, and the frg app prefix for multi-repository applications. Use it to read any frg command line and to find the flags a command accepts.

Command pattern

Workflow commands use a target and an operation:

bash

frg [GLOBAL OPTIONS] <target> <operation> [OPTIONS]

Part	Meaning	Examples
Target	The entity you work with	`issue`, `code`, `pr`, `docs`
Operation	The action to perform	`draft`, `review`, `merge`
Options	Flags that change agent selection, context, or output	`--edit`, `--lite`, `--agent github_copilot`

frg ask and frg run are standalone workflow commands without an operation. They take a question or task as an argument:

bash

frg ask "Where is authentication handled?"
frg run --task-file my-refactoring.md

Command types

frg --help groups commands into two types.

Type	Commands	What they do
Utility	`config`, `guide`, `shell`, `status`, `diagnose`, `workflow`, `learn`, `app`	Static operations: configuration, completions, diagnostics, stateful workflow management. See Utility Commands.
Workflow (AI agent-driven)	`issue`, `backlog`, `code`, `pr`, `docs`, `ticket`, `sec`, `ask`, `run`	Forge builds a prompt and runs your configured AI coding agent. See Workflow Commands.

Note: A few utility commands also call the AI agent: frg config init --interactive and frg app discover --auto use it to suggest metadata.

Workflow command groups

Target	Operations
`issue`	`draft`, `publish`, `review`, `plan`, `triage`, `split`, `ask`
`backlog`	`create`, `review`, `rank`, `ask`
`code`	`create`, `review`, `refactor`, `document`, `build`, `test`, `ask`
`pr`	`draft`, `publish`, `review`, `merge`, `ask`
`docs`	`create`, `build`, `ask`
`ticket`	`triage`, `respond`, `ask`, `correlate`
`sec`	`audit`, `patch`, `ask`
`ask`	(standalone)
`run`	(standalone)

Global options

Global options go directly after frg.

Option	Description
`--tail`	Streams trace file content in real time, similar to `tail -f`. Requires an active job context (`FORGE_ISSUE_ID`). Without `--continue`, exits after 5 minutes of inactivity.
`--continue`	Used with `--tail`. Follows newer trace files in the active job's `traces/` directory, and trace files of standalone `frg ask` and `frg run` commands. Adapts when `FORGE_ISSUE_ID` or `FORGE_TICKET_ID` changes. Never exits due to inactivity; stop it with Ctrl+C.
`-q`, `--quiet`	Suppresses all output except errors. Also accepted by every subcommand.
`-V`, `--version`	Prints the version.
`-h`, `--help`	Prints help.

bash

FORGE_ISSUE_ID=42 frg --tail
FORGE_ISSUE_ID=42 frg --tail --continue

See Progress Tracking for polling intervals and usage patterns.

Shared workflow flags

Most workflow commands accept the following flags. The exact set differs per command, so check frg <target> <operation> --help before you script a command.

Flag	Description
`--clear`	Clears the existing agent session and starts fresh.
`--retry [<INSTRUCTIONS>]`	Continues the previous session with a prompt to complete missing outputs. Optional text adds custom instructions. Cannot be used with `--clear`.
`--auto-retry`	Retries once automatically if output validation finds missing outputs. Cannot be used with `--clear`.
`-a`, `--agent <NAME>`	Selects the AI coding agent: `claude_code`, `github_copilot`, or `opencode`.
`-r`, `--role <ROLE>`	Overrides the AI role: `product_manager`, `software_engineer`, `software_architect`, `technical_writer`, `security_analyst`, `sre`. Mutually exclusive with `--custom-agent`.
`--custom-agent <NAME>`	Selects a custom agent configuration inside your AI coding agent. Mutually exclusive with `--role`.
`-m`, `--model <MODEL>`	Overrides the model configured in `agents.toml`.
`--print-prompt`	Displays the compiled prompt without running the agent.
`-c`, `--context-file <FILE>`	Adds a file path as context. Repeatable.
`--context-dir <DIR>`	Adds a directory as a context source. Repeatable. Maximum 100 files per directory and 1 MB per file; binary files and hidden directories are skipped.
`--edit [<INSTRUCTIONS>]`	Customizes output with inline instructions or an `edit.md` file.
`--lite`	Produces a lighter, faster result. The meaning differs per command.
`--lite-edit [<INSTRUCTIONS>]`	Combines `--lite` with edit instructions, inline or from `lite-edit.md`.
`--bypass-safety-checks`	Bypasses prompt-injection safety validation. Bypassed attempts are logged.

Per-command differences

Every workflow command accepts the flags from --clear through --context-dir, plus --bypass-safety-checks. The modifier flags depend on the command:

Modifier flags	Commands
`--edit`, `--lite`, `--lite-edit`	`issue draft`, `issue review`, `issue plan`, `code review`, `pr draft`, `pr review`
`--edit` only	`backlog create`, `backlog review`, `backlog rank`, `code document`, `docs create`, `sec patch`, `ticket triage`, `ticket respond`
`--fix [<INSTRUCTIONS>]` (inline or `fix.md`)	`code create`, `code refactor`, `pr merge`
`--auto-fix <LEVEL>` (`issues`, `critical`, `major`, `minor`, `suggestions`, `all`)	`code review`
None	All `ask` operations, `issue publish`, `issue triage`, `issue split`, `code build`, `code test`, `docs build`, `pr publish`, `sec audit`, `ticket correlate`

The standalone commands have extra options:

Command	Extra options
`ask`	Optional `[QUESTION]` argument (or `question.md`), and `--tail` to follow agent output in real time.
`run`	Optional `[TASK]` argument (or `task.md`), `--task-file <FILE>`, and `--tail`.

For the modifier flags, see Modifiers and Lite Mode. For every flag of every command, see the Command Reference.

Examples

bash

# Draft an issue
frg issue draft

# Draft with inline editing instructions
frg issue draft --edit "Add acceptance criteria for error handling"

# Lightweight implementation plan with a specific agent
frg issue plan --lite --agent github_copilot

# Create code using fix instructions from fix.md
frg code create --fix

# Review code and automatically fix critical issues
frg code review --auto-fix critical

# Add architecture notes as context and preview the prompt
frg code refactor --context-dir docs/architecture --print-prompt

Help

bash

frg --help # All commands and global options
frg issue --help # Operations for the issue target
frg issue draft --help # Flags for one operation

frg <command> -h prints a short summary; --help prints the full description.

Command context

Workflow commands that operate on a work item need a job context.

Context	Set with	Used by
Issue ID	`frg config set-issue <ISSUE_ID>` or `FORGE_ISSUE_ID`	`issue`, `code`, `pr`, and related commands
Ticket ID	`frg config set-ticket <TICKET_ID>` or `FORGE_TICKET_ID`	`ticket` commands
PR ID	`frg config set-pr <PR_ID>` or `FORGE_PR_ID`	`pr` commands

The set-* commands write to .forge/context.toml. Run frg config show-context to see the current values and their source.

bash

export FORGE_ISSUE_ID=123
export FORGE_PR_ID=456
frg pr review

When context is missing, Forge stops with an error such as No job ID set. Set FORGE_ISSUE_ID or FORGE_TICKET_ID environment variable. A PR ID alone is not enough: PR context requires an associated Issue ID or Ticket ID.

frg ask and frg run do not require issue context.

Command discovery

After you install completions with frg shell install <SHELL>, press Tab to list targets, operations, and flags:

bash

frg <TAB>
frg issue <TAB>
frg issue draft --<TAB>

See Shell Completions.

Application commands

The frg app prefix runs a command across the repositories of a multi-repository application defined in application.toml.

bash

frg app <target> <operation> [OPTIONS]

Available targets: issue, backlog, code, pr, docs, ticket, sec, ask, run. For ask and run, use the default operation, for example frg app ask default. frg app discover finds the repositories.

Prerequisites

Create the application configuration in the application root:

bash

frg config init --app

Opt in each child repository by setting allow_app in its .forge/config/project.toml to the application UUID:

toml

[project]
allow_app = "550e8400-e29b-41d4-a716-446655440000"

Discover the repositories. The results are saved to the [[repositories]] section of application.toml:

bash

  frg app discover
  frg app status                # Show where each repository's output landed

Use frg app discover --auto to generate project.toml files for discovered repositories that lack one.

See Multi-Repository Applications for the configuration details.

Execution modes

The app_workflow setting of an operation in commands.toml selects the mode.

Mode	When	Behavior
Direct execution (default)	The operation has no `app_workflow`	One AI invocation from the application root, with application context.
Workflow execution	The operation sets `app_workflow`	Runs the named workflow in each child repository through `frg workflow run`. Context is propagated to each repository's `.forge/context.toml`.

Built-in operations that use workflow execution:

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

All other app commands use direct execution. The help for workflow-mode commands includes NOTE: This command uses workflow execution mode.

To change the mode, override the operation in .forge/config/commands.toml. Run frg config export --commands to get a template.

toml

[[commands]]
target = "issue"

[[commands.operations]]
name = "plan"
app_workflow = "issue-to-plan"

Flags in each mode

Direct-execution commands accept the shared workflow flags, such as --clear, --retry, --auto-retry, --agent, --role, --custom-agent, --model, --print-prompt, --context-file, --context-dir, and --edit. app code review also accepts --auto-fix.

Workflow-execution commands accept these flags:

Flag	Description
`--start-from <STEP_NAME>`	Starts from a specific workflow step instead of the initial state.
`--bypass-approvals`	Skips approval gates (for CI/automation).
`--dry-run`	Validates the workflow without executing.
`-q`, `--quiet`	Suppresses all output except errors.

Forge rejects agent and context overrides in workflow execution, because the workflow configuration defines them. For example: --model is not supported for workflow execution. The same applies to --agent, --role, --context-file, and --clear.

Note: --lite is not supported for frg app commands. Forge reports --lite flag is not supported for 'frg app' commands. Multi-repository operations require comprehensive detail.

bash

frg app issue draft --edit       # Interactive editing
frg app code review --fix        # Include fix suggestions
frg app issue draft --model claude-opus-4.8
frg app issue draft --agent custom-agent
frg app issue draft --role security_expert
frg app issue draft --role none   # skip the persona prompt for this run
frg app issue draft --context-file ./extra-context.txt
frg app issue draft --clear      # Clear job directory first
frg app issue draft --quiet      # Suppress output

Allowed flags:

--edit, --fix: Interactive modifiers
--model, --agent, --role: Agent configuration
--context-file: Additional context
--clear: Clear previous output
--auto-retry: Automatic retry on failure
--quiet: Minimal output

Rejected flags:

--lite: Never supported for multi-repo operations (comprehensive detail required)

Workflow Execution Flags

These flags work with workflow execution commands:

bash

frg app issue plan --quiet                    # Suppress output
frg app issue plan --bypass-approvals         # Skip approval gates
frg app issue plan --start-from review_code   # Resume from step
frg app issue plan --dry-run                  # Validate without executing
frg app issue plan --max-workers 5            # Parallel execution limit

Allowed flags:

--quiet, -q: Suppress progress output
--bypass-approvals: Skip approval gates (for CI/automation)
--start-from <step>: Resume workflow from specific step
--dry-run: Validate workflow without execution
--max-workers N: Limit parallel repository execution (default: 3)

Rejected flags (with helpful error messages):

--model, --agent, --role: Model/agent selection is defined in workflow configuration. Role prompting can still be disabled for workflow runs via roles = "disabled" or role = "none" in commands.toml.
--context-file: Context is propagated via .forge/context.toml, not flags
--edit, --fix: Workflow run non-interactively across multiple repositories
--clear: Workflow context is managed per child repository
--lite: Never supported for app commands

Context Propagation

Application commands share context across repositories:

Shared Context:

Issue ID: Same issue applies to all repositories
Ticket ID: Same ticket applies to all repositories

Per-Repository Context:

PR ID: Generated independently for each repository
Job outputs: Stored in each repository's .forge/work/ directory

Context File: Context is written to .forge/context.toml in each child repository:

toml

[context]
issue_id = "123"
ticket_id = "456"
# pr_id is repository-specific, generated during workflow

Examples

Example 1: Draft Multi-Repository Issue

bash

cd /path/to/my-application
frg app discover

frg app issue draft # Direct: one draft with application context

export FORGE_ISSUE_ID=123
frg app issue plan --dry-run # Validate the per-repository workflow
frg app issue plan # Run issue-to-plan in each repository
frg app code create --bypass-approvals

Troubleshooting application commands

`No repositories defined in application.toml.`

Cause: Discovery has not run, or it found no repository with a matching allow_app value.

Solution:

Check that each child repository's .forge/config/project.toml sets allow_app to the UUID in application.toml.
Run frg app discover. Add --force to overwrite the existing [[repositories]] section.
Run frg config show --verbose to confirm the application configuration.

`--model is not supported for workflow execution.`

Cause: You passed an agent or context override to a workflow-execution command.

Solution: Remove the flag, and set the model or agent in the workflow configuration instead.

bash

# Run workflows in 5 repositories at a time
frg app issue plan --max-workers 5

# Quiet mode for CI/automation
frg app issue plan --quiet --bypass-approvals

Example 4: Custom App Workflow Commands

Users can add custom commands with workflow execution:

toml

# .forge/config/commands.toml
[[commands]]
target = "deploy"

[[commands.operations]]
name = "staging"
description = "Deploy to staging"
app_workflow = "deploy-staging"    # Custom workflow

Then use:

bash

frg app deploy staging    # Runs custom workflow in each repo

Status Tracking

Command execution shows per-repository progress:

Executing workflow 'issue-to-plan' in 3 repositories
  [✓] api-service     (12.3s)
  [✓] web-frontend    (8.7s)
  [⚠] worker-service  (failed - see logs at .forge/work/job_123/logs/)

2 of 3 repositories completed successfully

Status Icons:

[✓] - Completed successfully
[⚠] - Failed (with log path)
[⏳] - In progress
[⏸] - Awaiting approval

In-progress state detail: While a repository is In Progress, the live table appends the child workflow's current internal state in parentheses, e.g. In Progress (review_requested), sourced from the same polled status the parent already tracks. The suffix only appears once a state has been polled and disappears once the row reaches a terminal state (Done, Failed, etc.); the post-run summary shows the identical, sanitized state name using a [state] bracket instead.

Activity indicator: Below the table, a pulsing activity line reports elapsed runtime with minute-and-second precision (e.g. elapsed: 3m 12s, elapsed: 1h 1m 1s), rolling over into hours and days for long-running workflows, so a healthy long-running command stays visibly distinguishable from a hung one. This line only appears on interactive terminals; quiet mode and non-TTY output are unaffected.

Best Practices

Use direct execution for analysis: Issue drafting, code review work best with full application context
Use workflow execution for implementation: Code creation, PR creation need per-repo independence
Control parallelism: Use --max-workers to avoid rate limiting or resource exhaustion
Monitor status: Watch for failures and check logs in failed repositories
Propagate context: Always set FORGE_ISSUE_ID before starting application workflows
Test incrementally: Try commands on single repos before scaling to full application

Troubleshooting

"No repositories found"

Cause: Application has no discovered repositories

Solutions:

bash

frg app discover                 # Discover repositories
frg app status                   # Show where each repository's output landed
frg config show --sources        # Verify discovery results

"Repository UUID mismatch"

Cause: Child repository's allow_app doesn't match application UUID

Solutions:

bash

# Check application UUID
grep 'id =' .forge/config/application.toml

# Update child repository
cd child-repo
echo 'allow_app = "uuid-from-above"' >> .forge/config/project.toml

"Workflow not supported"

Cause: Unsupported flags for workflow execution mode

Solution: Remove unsupported flags:

bash

# ❌ Wrong - --model not supported in workflow mode
frg app issue plan --model claude-opus-4.8

# ✅ Correct - model defined in workflow configuration
frg app issue plan