Command Reference

Updated on Oct 6, 2026

This page lists every command, subcommand, argument, and option of the Forge CLI, taken from the --help output of the released binary. Use it to look up exact syntax. For task-oriented guidance, follow the links in each section.

Tip: Run frg <command> --help for the help text of your installed version.

How to read this reference

Notation	Meaning
`<VALUE>`	Required argument or option value.
`[VALUE]`	Optional argument or option value. For example, `--retry [<INSTRUCTIONS>]` works with or without text.
`[OPTIONS]`	Zero or more options.
`[COMMAND]` / `<COMMAND>`	Optional or required subcommand.
`<name\|--all>`	Provide either a name or the `--all` option.
`-a, --agent`	Short and long forms of the same option.

Every command also accepts -q, --quiet (suppress all output except errors) and -h, --help (print help). The option tables omit these two options.

Forge has two command types:

Utility commands run static operations: config, guide, shell, status, diagnose, workflow, learn, and app discover.
Workflow commands use an AI coding agent: issue, backlog, code, pr, docs, ticket, sec, ask, run, and the app operations. They need a configured agent and a valid license.

Command map

text

frg [OPTIONS] [COMMAND]
├── config Configuration management
│ ├── validate Validate configuration files
│ ├── lock Validate configuration and generate lockfile
│ ├── init Initialize frg configuration
│ ├── export Export workflows and prompts to .forge/ for customization
│ ├── set-issue Set current Issue ID (supports GitHub, JIRA, Azure DevOps, etc.)
│ ├── set-pr Set current GitHub Pull Request ID
│ ├── set-service Set current service (for monorepo configurations)
│ ├── set-ticket Set current Ticket ID (supports Zendesk, ServiceNow, etc.)
│ ├── show-context Display current context configuration
│ ├── clear-context Clear workflow context (Issue ID and PR ID)
│ ├── clear-issue Clear Issue ID from context
│ ├── clear-pr Clear PR ID from context
│ ├── clear-service Clear service selection from context
│ ├── clear-ticket Clear Ticket ID from context
│ ├── user Set user identity for OpenSearch reporting
│ └── show Display comprehensive Forge configuration state
├── guide Open Forge user guide
│ └── open Open user guide in browser
├── shell Manage shell integration
│ ├── install Install shell completions
│ ├── uninstall Uninstall shell completions
│ └── generate Generate completion script without installing
├── status Check frg configuration and agent status
├── diagnose Collect diagnostic information and assess frg readiness
├── workflow Manage user-defined stateful workflows
│ ├── list List available stateful workflows
│ ├── run Execute a stateful workflow
│ ├── status Show status of running or paused workflows
│ ├── approve Submit an approval for a pending workflow
│ ├── reject Reject a pending workflow approval
│ ├── unlock Release the repository workflow lock
│ ├── graph Generate a Mermaid diagram of a workflow
│ └── validate Validate a workflow definition without executing
├── learn Interactive tutorials for learning frg
│ ├── init Configure coding agent for tutorials
│ ├── list List all available tutorials
│ ├── run Run a specific tutorial
│ └── next Run the next incomplete tutorial
├── app Application management commands
│ ├── discover Discover repositories that have opted-in to this application
│ ├── 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 default
│ └── run default
├── issue Work item planning and management
│ ├── draft Create a local issue draft. Use --lite for simple changes, --edit to customize with your instructions
│ ├── publish Publish local draft to issue tracking system
│ ├── review Review issue for completeness and quality
│ ├── plan Generate detailed implementation plan. Use --lite for simple features/bug fixes
│ ├── triage Evaluate and prioritize issue
│ ├── split Split large issue into smaller work items
│ └── ask Ask questions about current issue context
├── backlog Strategic planning and backlog management
│ ├── create Create strategic planning document
│ ├── review Review backlog health and quality
│ ├── rank Rank backlog items by priority
│ └── ask Ask questions about backlog strategy
├── code Code and build operations
│ ├── create Generate new code
│ ├── review Review code quality
│ ├── refactor Restructure existing code
│ ├── document Generate code documentation
│ ├── build Compile and build code
│ ├── test Execute test suites
│ └── ask Ask questions about code
├── pr Pull request operations
│ ├── draft Create pull request draft
│ ├── publish Publish pull request draft to GitHub
│ ├── review Review pull request
│ ├── merge Analyze merge safety and prepare merge
│ └── ask Ask questions about pull request
├── docs Project documentation and guides
│ ├── create Generate documentation or guides
│ ├── build Build documentation from code
│ └── ask Ask questions about documentation
├── ticket Customer support ticket investigation and response
│ ├── triage Analyze ticket to determine severity and identify missing information
│ ├── respond Investigate root cause and generate comprehensive response
│ ├── ask Ask questions about ticket context
│ └── correlate Analyze patterns across multiple related tickets
├── sec Security scanning and vulnerability remediation
│ ├── audit Audit project for security vulnerabilities using SAST findings
│ ├── patch Generate remediation patch for a specific security finding
│ └── ask Ask questions about security findings and remediation
├── ask Context-free Q&A about the codebase
└── run Execute arbitrary tasks in the codebase

Global options

These options apply to frg itself, for example frg --tail.

Option	Description	Values / default
`--tail`	Stream the active job's trace file in real time, like `tail -f`. Requires an active job context (`FORGE_ISSUE_ID` or `FORGE_TICKET_ID`). Exits after 5 minutes of inactivity unless you add `--continue`.	Flag
`--continue`	With `--tail`, keep monitoring: switch to newer trace files in the active job, follow `frg ask` and `frg run` traces, and adapt when the Issue ID or Ticket ID changes. Never exits on inactivity; stop with Ctrl+C.	Flag
`-q, --quiet`	Suppress all output except errors.	Flag
`-h, --help`	Print help. `-h` prints a summary; `--help` prints the full text.	Flag
`-V, --version`	Print the version.	Flag

Long Flag	Short	Available In	Description
`--agent`	`-a`	All workflow operations	Select AI coding agent
`--role`	`-r`	All workflow operations	Override AI role (use `none` to disable role prompting)
`--context-file`	`-c`	All workflow operations	Add file context (repeatable)
`--context-dir`	—	All workflow operations	Add directory context (repeatable)
`--model`	`-m`	All workflow operations	Override AI model

Utility Command Flags

Long Flag	Short	Available In	Description
`--file`	`-f`	`config validate`	Specify config file
`--target`	`-t`	`config export`	Export specific target
`--verbose`	`-v`	`status`	Show detailed output

Flags Without Short Versions

These flags intentionally do not have short versions:

Long Flag	Reason
`--force`	Destructive operation - requires explicit typing
`--tail`	Debug feature - not for routine use
`--print-prompt`	Debug feature - not for routine use
`--custom-agent`	Power-user feature - rarely used
`--manual`	One-time setup - clarity over brevity

Usage Examples:

bash

FORGE_ISSUE_ID=42 frg --tail --continue

See Progress Tracking and Troubleshooting --tail.

Common workflow options

Every workflow subcommand accepts the options below, except the app commands that run in workflow execution mode (see frg app). Each subcommand section lists only its additional options.

Option	Description	Values / default
`--clear`	Discard the agent session for this command group and start a new one. Cannot be combined with `--retry` or `--auto-retry`. See Session Context.	Flag
`--retry [<INSTRUCTIONS>]`	Continue the previous session with a prompt that lists the missing output files; optional text adds your own instructions. Requires an existing session.	Optional value
`--auto-retry`	Retry once automatically, with the default missing-outputs prompt, when output validation finds missing files.	Flag
`-a, --agent <NAME>`	AI coding agent for this run. See Agent Setup.	`claude_code`, `github_copilot`, `opencode`
`-r, --role <ROLE>`	Override the default AI role. Cannot be combined with `--custom-agent`.	`product_manager`, `software_engineer`, `software_architect`, `technical_writer`, `security_analyst`, `sre`
`--custom-agent <NAME>`	Use a custom agent configuration of your coding agent, for example `python-expert`. Cannot be combined with `--role`. See Custom Agent Configurations.
`-m, --model <MODEL>`	Override the model from `agents.toml`. Available models depend on the agent; `frg status` lists them. See AI Model Selection.
`--print-prompt`	Display the compiled prompt without running the agent.	Flag
`-c, --context-file <FILE>`	Add a file path as context. The agent reads the file when needed. Relative and absolute paths work.	Repeatable
`--context-dir <DIR>`	Add a directory as context. Paths are relative to the current directory. Binary files and hidden directories are skipped; at most 100 files per directory and 1 MB per file. See Context Usage Patterns.	Repeatable
`--bypass-safety-checks`	Skip prompt-injection validation for input you verified manually. Bypasses are logged for audit. See Prompt Safety Validation.	Flag

Modifier options

Modifiers change what an operation produces. Which modifiers an operation accepts differs per operation.

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize the output with instructions passed inline or in `edit.md`. See Modifiers.	Optional value
`--lite`	Produce a shorter, focused variant. See Lite Mode.	Flag
`--lite-edit [<INSTRUCTIONS>]`	Combine `--lite` with instructions passed inline or in `lite-edit.md`.	Optional value
`--fix [<INSTRUCTIONS>]`	Apply fix instructions passed inline or in `fix.md`.	Optional value
`--dev`	Focus documentation on a developer or API audience.	Flag
`--auto-fix <LEVEL>`	Automatically fix review findings by severity.	`issues`, `critical`, `major`, `minor`, `suggestions`, `all`

Option availability

✓ means the operation accepts the option. All operations accept the common workflow options.

Command	`--edit`	`--lite`	`--lite-edit`	`--fix`	`--dev`	`--auto-fix`	`--task-file`	`--tail`
`frg issue draft`	✓	✓	✓
`frg issue publish`
`frg issue review`	✓	✓	✓
`frg issue plan`	✓	✓	✓
`frg issue triage`
`frg issue split`
`frg issue ask`
`frg backlog create`	✓
`frg backlog review`	✓
`frg backlog rank`	✓
`frg backlog ask`
`frg code create`				✓
`frg code review`	✓	✓	✓			✓
`frg code refactor`				✓
`frg code document`	✓
`frg code build`
`frg code test`
`frg code ask`
`frg pr draft`	✓	✓	✓
`frg pr publish`
`frg pr review`	✓	✓	✓
`frg pr merge`				✓
`frg pr ask`
`frg docs create`	✓
`frg docs build`					✓
`frg docs ask`
`frg ticket triage`	✓
`frg ticket respond`	✓
`frg ticket ask`
`frg ticket correlate`
`frg sec audit`
`frg sec patch`	✓
`frg sec ask`
`frg ask`								✓
`frg run`							✓	✓

Context requirements

Workflow commands operate on the current work item. Set it with a frg config set-* command, which writes .forge/context.toml, or with an environment variable, which takes precedence.

Context	Set with	Environment variable	Used by
Issue ID	`frg config set-issue <ISSUE_ID>`	`FORGE_ISSUE_ID`	`issue`, `code`, `pr`, and `docs` jobs in `.forge/work/job_<id>/`
PR ID	`frg config set-pr <PR_ID>`	`FORGE_PR_ID`	`pr` operations. A PR context also needs an Issue ID or Ticket ID.
Ticket ID	`frg config set-ticket <TICKET_ID>`	`FORGE_TICKET_ID`	`ticket` operations
Service	`frg config set-service <SERVICE_NAME>`	—	Monorepo projects

frg ask and frg run need no context. Run frg config show-context to see the current values and their sources. See Context Configuration.

`frg config`

Configuration management. Utility command.

text

frg config [OPTIONS] [COMMAND]

Common Use Cases:

Starting a new feature or bug report
Brainstorming requirements
Creating well-structured issue descriptions

Related Commands: issue publish, issue review

`frg issue publish`

Description: Publish a local issue draft to your issue tracking system (GitHub, GitLab, etc.).

Required Context: Local issue draft file

Available Modifiers: None

Usage Examples:

bash

# Publish issue to tracking system
frg issue publish

Common Use Cases:

Publishing completed issue drafts
Creating issues in your tracking system
Syncing local work with team

Related Commands: issue draft, config set-issue

`frg issue review`

Description: Review an issue for completeness, clarity, and quality.

Required Context: FORGE_ISSUE_ID (set via env or config)

Available Modifiers: --edit

Usage Examples:

bash

# Review current issue
export FORGE_ISSUE_ID=123
frg issue review

# Review with editing instructions
frg issue review --edit

Common Use Cases:

Ensuring issue quality before starting work
Identifying missing requirements
Improving issue clarity

Related Commands: issue plan, issue triage, config set-issue

`frg issue plan`

Description: Generate a detailed implementation plan for an issue.

Required Context: FORGE_ISSUE_ID

Available Modifiers: --edit, --lite, --lite-edit

Usage Examples:

bash

# Generate implementation plan
frg config set-issue 123
frg issue plan

# Plan with editing instructions
frg issue plan --edit

# Lightweight plan for simple changes
frg issue plan --lite

Common Use Cases:

Breaking down complex issues
Creating step-by-step implementation guides
Estimating work scope

Related Commands: issue review, issue split, code create

`frg issue triage`

Description: Evaluate and prioritize an issue based on impact, effort, and dependencies.

Required Context: FORGE_ISSUE_ID

Available Modifiers: None

Usage Examples:

bash

# Triage an issue
export FORGE_ISSUE_ID=123
frg issue triage

Common Use Cases:

Prioritizing backlog items
Assessing issue urgency
Resource allocation planning

Related Commands: backlog rank, issue review

`frg issue split`

Description: Split a large issue into smaller, manageable work items.

Required Context: FORGE_ISSUE_ID

Available Modifiers: None

Usage Examples:

bash

# Split large issue
frg config set-issue 123
frg issue split

Common Use Cases:

Breaking down epics
Creating sprint-sized tasks
Parallel work distribution

Related Commands: issue plan, backlog create

`frg issue ask`

Description: Ask questions about the current issue context.

Required Context: FORGE_ISSUE_ID

Available Modifiers: None

Usage Examples:

bash

# Ask about issue
export FORGE_ISSUE_ID=123
frg issue ask "What are the main technical challenges?"

# Query issue requirements
frg issue ask "Are there any missing dependencies?"

Common Use Cases:

Understanding issue requirements
Clarifying technical details
Exploring implementation options

Related Commands: All other issue operations

Backlog Operations

Commands for strategic planning and backlog management.

`frg backlog create`

Description: Create a strategic planning document or backlog.

Required Context: None

Available Modifiers: --edit

Usage Examples:

bash

# Create backlog document
frg backlog create

# Create with editing instructions
frg backlog create --edit

Common Use Cases:

Quarterly planning
Product roadmap creation
Feature prioritization

Related Commands: backlog review, backlog rank

`frg backlog review`

Description: Review backlog health, quality, and completeness.

Required Context: Existing backlog document

Available Modifiers: --edit

Usage Examples:

bash

# Review backlog
frg backlog review

# Review with editing instructions
frg backlog review --edit

Common Use Cases:

Sprint planning preparation
Identifying backlog gaps
Quality assurance

Related Commands: backlog rank, issue triage

`frg backlog rank`

Description: Rank backlog items by priority, impact, and dependencies.

Required Context: Existing backlog document

Available Modifiers: --edit

Usage Examples:

bash

# Rank backlog items
frg backlog rank

# Rank with editing instructions
frg backlog rank --edit

Common Use Cases:

Sprint planning
Resource allocation
Release planning

Related Commands: backlog review, issue triage

`frg backlog ask`

Description: Ask questions about backlog strategy and planning.

Required Context: None (context-dependent)

Available Modifiers: None

Usage Examples:

bash

# Query backlog strategy
frg backlog ask "What should we prioritize for Q2?"

# Ask about technical debt
frg backlog ask "How much technical debt is in the backlog?"

Common Use Cases:

Strategic planning
Understanding priorities
Backlog analysis

Related Commands: All other backlog operations

`frg backlog plan`

Description: Transform .forge/work/backlog/roadmap.md into a structured plan file (plan.json by default). Deterministic — parses the roadmap directly and does not invoke a coding agent.

Required Context: Existing roadmap.md (or --input pointing to one)

Available Modifiers: --input, --output, --format, --force, --validate, --no-validate, --dispatch-format, --summary, --graph, --quiet

Usage Examples:

bash

# Generate a plan from the roadmap
frg backlog plan

# Generate the flat format frg dispatch consumes
frg backlog plan --dispatch-format

# Validate or summarize an existing plan
frg backlog plan --validate
frg backlog plan --summary --graph

Common Use Cases:

Producing a dispatch-ready work queue from a roadmap
Validating a previously generated plan file
Inspecting plan structure and dependencies

Related Commands: backlog create, backlog rank

Code Operations

Commands for code generation, review, and maintenance.

`frg code create`

Description: Generate new code with AI assistance.

Required Context: None (optional: FORGE_ISSUE_ID)

Available Modifiers: --fix

Usage Examples:

bash

# Create code for current issue
export FORGE_ISSUE_ID=123
frg code create

# Create with fix instructions
frg code create --fix

Common Use Cases:

Implementing new features
Creating boilerplate code
Generating test cases

Related Commands: issue plan, code review, code test

`frg code review`

Description: Review code quality, patterns, and best practices.

Required Context: None (reviews working directory changes)

Available Modifiers: --edit

Available Options: --auto-fix <LEVEL> (requires .forge/work/job_<id>/code/review.md; run frg code review first)

Usage Examples:

bash

# Review code changes
frg code review

# Review with editing instructions
frg code review --edit

# Auto-fix all issues from review
frg code review --auto-fix issues

# Auto-fix only critical issues
frg code review --auto-fix critical

Common Use Cases:

Pre-commit code review
Code quality improvement
Learning best practices
Automatic issue fixing

Related Commands: pr review, code refactor

`frg code refactor`

Description: Restructure existing code to improve quality and maintainability.

Required Context: None (operates on current directory)

Available Modifiers: --fix

Usage Examples:

bash

# Refactor code
frg code refactor

# Apply refactorings using your instructions
frg code refactor --fix

Common Use Cases:

Technical debt reduction
Code modernization
Performance optimization

Related Commands: code review, code test

`frg code document`

Description: Generate code documentation (comments, README, API docs).

Required Context: None (documents current directory)

Available Modifiers: --edit

Usage Examples:

bash

# Generate documentation
frg code document

# Generate with editing instructions
frg code document --edit

Common Use Cases:

API documentation
Code comment generation
README updates

Related Commands: docs create, docs build

`frg code build`

Description: Compile and build code, diagnose build issues.

Required Context: None (builds current project)

Available Modifiers: None

Usage Examples:

bash

# Build project
frg code build

Common Use Cases:

Fixing build errors
Dependency resolution
Build optimization

Related Commands: code test, code create

`frg code test`

Description: Execute test suites and analyze test results.

Required Context: None (tests current project)

Available Modifiers: None

Usage Examples:

bash

# Run tests
frg code test

Common Use Cases:

Running test suites
Fixing failing tests
Test coverage analysis

Related Commands: code build, code review

`frg code ask`

Description: Ask questions about code in your repository.

Required Context: None (context-dependent)

Available Modifiers: None

Usage Examples:

bash

# Ask about code architecture
frg code ask "How does authentication work?"

# Query specific functionality
frg code ask "Where is user validation implemented?"

Common Use Cases:

Code exploration
Understanding architecture
Finding implementations

Related Commands: All other code operations

PR Operations

Commands for pull request management.

`frg pr draft`

Description: Create a pull request draft with generated title and description.

Required Context: FORGE_ISSUE_ID, FORGE_PR_ID (optional)

Available Modifiers: --edit

Usage Examples:

bash

# Create PR draft
export FORGE_ISSUE_ID=123
frg pr draft

# Create with editing instructions
frg pr draft --edit

Common Use Cases:

Creating pull requests
Generating PR descriptions
Linking PRs to issues

Related Commands: issue plan, pr review, config set-pr

`frg pr review`

Description: Review a pull request for quality, completeness, and best practices.

Required Context: FORGE_ISSUE_ID, FORGE_PR_ID

Available Modifiers: --edit

Usage Examples:

bash

# Review current PR
export FORGE_ISSUE_ID=123 FORGE_PR_ID=456
frg pr review

# Review with editing instructions
frg pr review --edit

Common Use Cases:

Pre-merge code review
Quality assurance
Finding potential issues

Related Commands: code review, pr merge

`frg pr merge`

Description: Analyze merge safety, check CI status, and prepare for merge.

Required Context: FORGE_ISSUE_ID, FORGE_PR_ID

Available Modifiers: --fix

Usage Examples:

bash

# Check merge readiness
frg config set-issue 123
frg config set-pr 456
frg pr merge

# Fix merge issues and CI failures
frg pr merge --fix

Common Use Cases:

Pre-merge validation
Fixing CI failures
Resolving merge conflicts

Related Commands: pr review, code test

`frg pr ask`

Description: Ask questions about a pull request.

Required Context: FORGE_ISSUE_ID, FORGE_PR_ID

Available Modifiers: None

Usage Examples:

bash

# Ask about PR
export FORGE_ISSUE_ID=123 FORGE_PR_ID=456
frg pr ask "What are the main changes in this PR?"

# Query PR impact
frg pr ask "Are there any breaking changes?"

Common Use Cases:

Understanding PR scope
Impact analysis
Review preparation

Related Commands: All other pr operations

Docs Operations

Commands for documentation management.

`frg docs create`

Description: Generate documentation or user guides.

Required Context: None (context-dependent)

Available Modifiers: --edit

Usage Examples:

bash

# Create documentation
frg docs create

# Create with editing instructions
frg docs create --edit

Common Use Cases:

User guide creation
Tutorial writing
Documentation updates

Related Commands: code document, docs build

`frg docs build`

Description: Build documentation from code (API docs, inline comments).

Required Context: None (builds from current directory)

Available Modifiers: --dev

Usage Examples:

bash

# Build documentation
frg docs build

# Build for developer audience
frg docs build --dev

Common Use Cases:

API documentation generation
Reference documentation
Developer documentation

Related Commands: code document, docs create

`frg docs ask`

Description: Ask questions about project documentation.

Required Context: None (context-dependent)

Available Modifiers: None

Usage Examples:

bash

# Ask about documentation
frg docs ask "What's missing from the user guide?"

# Query documentation coverage
frg docs ask "Which APIs are undocumented?"

Common Use Cases:

Documentation gap analysis
Finding documentation
Understanding docs structure

Related Commands: All other docs operations

Utility Commands

System and configuration management commands.

config

Configuration management for Forge CLI.

`frg config show`

Description: Display current Forge configuration.

Usage Example:

bash

frg config show

`frg config validate`

Description: Validate Forge configuration files for errors.

Usage Example:

bash

# Validate default config
frg config validate

# Validate specific file
frg config validate --file .forge/config/commands.toml

`frg config init`

Description: Initialize the .forge/ directory structure in your project.

Environment Support:

✅ Git repository: Full support with commit SHA tracking
✅ Non-git directory: Full support (commit SHA will be empty in logs)
✅ VS Code workspace: Works in any folder
✅ Docker container: Works without git

Usage Example:

bash

# Basic initialization (toolchain only)
frg config init

# Initialize with specific tools
frg config init --issues github_issues --code github

# Initialize with agent and model profile
frg config init --agent github_copilot --models balanced
frg config init --agent opencode --models stable

# Agent with default profile (stable)
frg config init --agent github_copilot

# Replace an existing agents.toml with a generated profile
frg config init --agent github_copilot --models balanced --force

# Edit an existing project.toml without the initial confirmation
frg config init --interactive --force

Flags:

--agent <AGENT> - AI agent to configure (required when using --models)
- github_copilot - GitHub Copilot CLI
- opencode - Multi-provider AI CLI
--models <PROFILE> - Model profile for cost/performance tradeoffs (default: stable)
- lite - Minimize costs
- balanced - Latest generation models
- stable - Predictable behaviour (default)
- heavy - Maximum quality
--issues <TRACKER> - Issue tracker integration
--tickets <PLATFORM> - Ticketing system integration
--code <HOST> - Code hosting platform integration
--force - Replace files selected by explicit initialization options

--force cannot be used alone or with --app. It affects only files selected by the other options: --agent selects agents.toml, tool options select toolchain.toml, and --interactive selects project.toml. In interactive mode, it skips the initial edit/cancel confirmation but keeps the per-field review prompts.

Output:

In a git repository:

Initializing .forge directory structure...
✓ Created .forge/ directory structure
  - .forge/config/   (configuration files)
  - .forge/work/     (job outputs)
  - .forge/prompts/  (custom prompts)
  Project root: /path/to/project

⚙  .gitignore patterns for frg:
    .forge/logs/
    .forge/cache/
    .forge/.context.lock
    .forge/.workflow.lock
    .forge/work/**/traces/.heartbeat
    .forge/config/opensearch.toml
    .forge/config/telemetry.toml
    # .forge/work/              (team decision - see docs)

  ℹ Commit: .forge/config/ and .forge/prompts/
  For detailed guidance: https://www.telerik.com/forge/documentation
In a non-git directory:

Initializing .forge directory structure... ✓ Created .forge/ directory structure

.forge/config/ (configuration files)
.forge/work/ (job outputs)
.forge/prompts/ (custom prompts)

Project root: /path/to/project Note: Not in a git repository

✓ Initialization complete!


**Common Use Cases**:
- Setting up Forge in a new project (git or non-git)
- Reinitializing after directory structure changes
- Creating temporary testing environments

**Version Control**: See [Version Control Setup](slug://version-control-setup) for comprehensive `.gitignore` patterns.

---

#### `frg config export`

**Description**: Export built-in workflow definitions to `.forge/config/commands.toml`.

**Usage Example**:
```bash
frg config export

Common Use Cases:

Customizing built-in workflows
Creating workflow templates
Understanding workflow structure

`frg config set-issue`

Description: Set the current issue ID in context.

Usage Example:

bash

# Set current issue
frg config set-issue 123

# Use in workflow
frg issue review

Common Use Cases:

Working with specific issues
Setting context for commands
Avoiding environment variables

Related Commands: config set-pr, config show-context

`frg config set-pr`

Description: Set the current PR ID in context.

Usage Example:

bash

# Set current PR
frg config set-pr 456

# Use in workflow
frg pr review

Common Use Cases:

Working with specific PRs
Setting context for commands
Avoiding environment variables

Related Commands: config set-issue, config show-context

`frg config set-base-branch`

Description: Set the project-level base branch/ref that newly created branches are forked from.

Usage Example:

bash

# Fork new branches from 'develop' instead of the repo's checked-out branch
frg config set-base-branch develop

Common Use Cases:

Teams whose default working branch is not the branch the agent happens to have checked out
Standardizing which ref feature branches fork from across the team

Prerequisites:

Run inside a frg project (.forge/config/project.toml must already exist; run frg config init first)

Notes:

This is a project-level, team-shared setting written to .forge/config/project.toml's [branch] table — not a per-job or per-user override. Commit the resulting change to share it with your team.

Related Commands: config validate

Related Documentation: Branch Behavior Configuration

`frg config show-context`

Description: Display current workflow context (issue ID, PR ID, service).

Usage Example:

bash

frg config show-context

Example Output:

Context Configuration:
  Issue ID:   123
  PR ID:      456
  Service:    api (services/api)

Related Commands: config set-issue, config set-pr, config set-service, config clear-context

`frg config clear-context`

Description: Clear both Issue ID and PR ID from the workflow context file.

Usage Example:

bash

# Set context
frg config set-issue 42
frg config set-pr 99

# Clear all context
frg config clear-context

# Verify context is empty
frg config show-context

Common Use Cases:

Switching between different issues/PRs
Resetting workflow context
Cleaning up after completing work

Note: This command only clears the context file (.forge/context.toml). If you have set FORGE_ISSUE_ID or FORGE_PR_ID environment variables, they must be manually unset:

bash

unset FORGE_ISSUE_ID FORGE_PR_ID

Related Commands: config set-issue, config set-pr, config show-context, config clear-issue, config clear-pr

`frg config clear-issue`

Description: Clear the Issue ID from the workflow context, preserving the PR ID.

Usage Example:

bash

# Set both values
frg config set-issue 42
frg config set-pr 99

# Clear only issue (PR preserved)
frg config clear-issue

# Verify - PR should still be set
frg config show-context

Common Use Cases:

Clearing issue context while maintaining PR context
Switching to a different issue while keeping same PR
Cleaning up partial context

Note: This command only clears the context file. If you have set the FORGE_ISSUE_ID environment variable, it must be manually unset:

bash

unset FORGE_ISSUE_ID

Related Commands: config clear-context, config clear-pr, config set-issue, config show-context

`frg config clear-pr`

Description: Clear the PR ID from the workflow context, preserving the Issue ID.

Usage Example:

bash

# Set both values
frg config set-issue 42
frg config set-pr 99

# Clear only PR (issue preserved)
frg config clear-pr

# Verify - issue should still be set
frg config show-context

Common Use Cases:

Clearing PR context while maintaining issue context
Switching to a different PR while keeping same issue
Cleaning up partial context

Note: This command only clears the context file. If you have set the FORGE_PR_ID environment variable, it must be manually unset:

bash

unset FORGE_PR_ID

Related Commands: config clear-context, config clear-issue, config set-pr, config show-context

`frg config set-service`

Description: Set the current service in context (for monorepo projects).

Usage Example:

bash

# Set current service
frg config set-service api

# Use in workflow
frg code implement

Common Use Cases:

Working with specific services in a monorepo
Providing service-specific context to AI agents
Switching between services

Prerequisites:

Monorepo mode must be enabled in project.toml
Service must be defined in [[monorepo.services]]

Related Commands: config clear-service, config show-context

Related Documentation: Monorepo Support Guide

`frg config clear-service`

Description: Clear service selection from context (reverts to project-wide mode).

Usage Example:

bash

# Set service
frg config set-service api

# Clear service selection
frg config clear-service

# Verify service is cleared
frg config show-context

Common Use Cases:

Switching to project-wide operations
Working across multiple services
Resetting service context after focused work

Related Commands: config set-service, config show-context

Related Documentation: Monorepo Support Guide

guide

Open Forge user documentation.

Description: Open the Forge user guide in your default browser.

Usage Examples:

bash

# Open full guide
frg guide

# Open specific section (if available)
frg guide getting-started

shell

Shell completion management.

`frg shell install`

Description: Install shell completions for your shell.

Usage Example:

bash

# Auto-detect and install
frg shell install

# Install for specific shell
frg shell install bash
frg shell install zsh
frg shell install fish

`frg shell uninstall`

Description: Uninstall shell completions.

Usage Example:

bash

frg shell uninstall

`frg shell generate`

Description: Generate shell completion script (for manual installation).

Usage Example:

bash

# Generate for bash
frg shell generate bash > frg-completions.bash

# Generate for zsh
frg shell generate zsh > _neo

status

System status check.

Description: Check Forge configuration, project root detection, and agent connectivity.

Usage Examples:

bash

# Quick status check
frg status

# Verbose diagnostics
frg status --verbose

Example Output:

Forge Status Check
=================

ℹ  Project Root: /path/to/your/project
   Detected via: .git/ directory
✓  Forge: Initialized
ℹ  Coding Agent: GitHub Copilot (authenticated)
✓  Toolchain: Configured
   Issue Tracker: github_issues (cli)
   Code Platform: github (cli)

Project Root Detection:

The status command shows how Forge detected your project root:

Detection Method	Meaning
`.git/` directory	Found git repository root
`.forge/` directory	Found existing Forge installation
current working directory	No markers found, using CWD

Common Use Cases:

Troubleshooting setup
Verifying configuration
Checking agent availability
Confirming project root detection

telemetry

Manage usage telemetry collection.

Subcommand	Description
`validate`	Validate configuration files
`lock`	Validate configuration and generate lockfile
`init`	Initialize frg configuration
`export`	Export workflows and prompts to .forge/ for customization
`set-issue`	Set current Issue ID (supports GitHub, JIRA, Azure DevOps, etc.)
`set-pr`	Set current GitHub Pull Request ID
`set-service`	Set current service (for monorepo configurations)
`set-ticket`	Set current Ticket ID (supports Zendesk, ServiceNow, etc.)
`show-context`	Display current context configuration
`clear-context`	Clear workflow context (Issue ID and PR ID)
`clear-issue`	Clear Issue ID from context
`clear-pr`	Clear PR ID from context
`clear-service`	Clear service selection from context
`clear-ticket`	Clear Ticket ID from context
`user`	Set user identity for OpenSearch reporting
`show`	Display comprehensive Forge configuration state

`frg config validate`

Validate configuration files.

text

frg config validate [OPTIONS]

Option	Description	Values / default
`-f, --file <FILE>`	Validate one configuration file.	Default: `.forge/config/commands.toml`

Example

bash

frg config validate --file .forge/config/agents.toml

`frg config lock`

Validate project.toml, toolchain.toml, agents.toml, and commands.toml and, if all pass, write .forge/.config_lock with the SHA-256 hash of each file. While a lockfile exists, workflow commands are blocked when a locked file changes until you run frg config lock again. Locking is opt-in.

text

frg config lock [OPTIONS]

Example

bash

frg config lock

`frg config init`

Initialize frg configuration.

text

frg config init [OPTIONS]

Option	Description	Values / default
`-i, --interactive`	Use AI to suggest a value for each `project.toml` metadata field; accept each suggestion with Enter or type your own value.	Flag
`--app`	Create `application.toml` instead of a project configuration. Combine with `--issues`, `--tickets`, `--scanner`, `--code`, `--agent`, and `--models` to also create `toolchain.toml` and `agents.toml`.	Flag
`--force`	Overwrite the files that other options select: `--agent` selects `agents.toml`; `--issues`, `--tickets`, or `--scanner` select `toolchain.toml`; `--interactive` selects `project.toml`. Cannot be used alone or with `--app`.	Flag
`--issues <TOOL>`	Issue tracker to configure in `toolchain.toml`.	For example `github_issues`, `jira`, `azure_devops`, `shortcut`, `local`
`--tickets <TOOL>`	Ticket tracker to configure in `toolchain.toml`.	For example `github_issues`, `jira`, `azure_devops`, `shortcut`, `local`
`--code <TOOL>`	Code platform to configure in `toolchain.toml`. Requires `--issues` or `--tickets`, and a tracker option requires `--code`.	For example `github`, `github_enterprise`, `bitbucket`, `azure_devops`, `local`
`--scanner <TOOL>`	Security scanner to configure in `toolchain.toml`.	For example `polaris`, `github_sast`
`--agent <AGENT>`	AI coding agent to configure in `agents.toml`. Without `--agent` and `--models`, only the toolchain is set up.	`claude_code`, `github_copilot`, `opencode`
`--models <PROFILE>`	Model profile for the generated `agents.toml`. See AI Model Selection.	`lite`, `balanced`, `stable`, `heavy`; Default: `stable` when `--agent` is set

Example

bash

frg config init --agent claude_code --models balanced --issues github_issues --code github

`frg config export`

Export built-in commands, prompts, workflows, skills, or security configuration to .forge/ (or .agents/skills/) for customization. Specify at least one export option.

text

frg config export [OPTIONS]

Option	Description	Values / default
`--commands`	Export a commented `commands.toml` template. Cannot be combined with `--skills` or `--security`.	Flag
`--prompts`	Export role and task prompts to `.forge/prompts/`.	Flag
`--workflows`	Export built-in workflows to `.forge/config/workflows/`.	Flag
`--skills`	Export built-in skill files (`SKILL.md`) to `.agents/skills/`.	Flag
`--security`	Export `.forge/config/.prompt-safety.toml` with the built-in detection rules.	Flag
`--all`	Export commands, prompts, and workflows.	Flag
`--scope <SCOPE>`	Destination for `--skills`: `project` writes `<repo>/.agents/skills/`, `user` writes `~/.agents/skills/`. By default, the scope follows the discovered configuration location.
`--force`	Overwrite existing files.	Flag
`-t, --target <TARGET>`	Export only one workflow target, for example `issue`.

Example

bash

frg config export --skills --scope user

`frg config set-issue`

Set current Issue ID (supports GitHub, JIRA, Azure DevOps, etc.).

text

frg config set-issue [OPTIONS] <ISSUE_ID>

Argument	Description
`<ISSUE_ID>`	Issue ID (e.g., 123, PROJ-456, AB#789).

Example

bash

frg config set-issue PROJ-456

`frg config set-pr`

Set current GitHub Pull Request ID.

text

frg config set-pr [OPTIONS] <PR_ID>

Argument	Description
`<PR_ID>`	GitHub Pull Request number.

Example

bash

frg config set-pr 128

`frg config set-service`

Set current service (for monorepo configurations).

text

frg config set-service [OPTIONS] <SERVICE_NAME>

Argument	Description
`<SERVICE_NAME>`	Service name to select.

Example

bash

frg config set-service api

`frg config set-ticket`

Set the current Ticket ID in .forge/context.toml for frg ticket commands, for example 123456 (Zendesk), INC0012345 (ServiceNow), or TICKET-42. FORGE_TICKET_ID overrides it.

text

frg config set-ticket [OPTIONS] <TICKET_ID>

Argument	Description
`<TICKET_ID>`	Ticket ID to set (e.g., 123456, INC0012345, TICKET-42).

Example

bash

frg config set-ticket INC0012345

`frg config show-context`

Show the current Issue ID, PR ID, Ticket ID, service, and user, including where each value comes from.

text

frg config show-context [OPTIONS]

Example

bash

frg config show-context

Example output:

text

Current Context Configuration:
────────────────────────────────────────
Issue ID: Not set
PR ID: Not set
Ticket ID: Not set
Service: Not set
User Name: jane
User Email: jane@example.com
────────────────────────────────────────

`frg config clear-context`

Remove the Issue ID and PR ID from .forge/context.toml. Unset FORGE_ISSUE_ID and FORGE_PR_ID yourself.

text

frg config clear-context [OPTIONS]

Example

bash

frg config clear-context
unset FORGE_ISSUE_ID FORGE_PR_ID

`frg config clear-issue`

Remove the Issue ID from .forge/context.toml and keep the PR ID. Unset FORGE_ISSUE_ID yourself.

text

frg config clear-issue [OPTIONS]

Example

bash

frg config clear-issue

`frg config clear-pr`

Remove the PR ID from .forge/context.toml and keep the Issue ID. Unset FORGE_PR_ID yourself.

text

frg config clear-pr [OPTIONS]

Example

bash

frg config clear-pr

`frg config clear-service`

Remove the monorepo service selection from .forge/context.toml.

text

frg config clear-service [OPTIONS]

Example

bash

frg config clear-service

`frg config clear-ticket`

Remove the Ticket ID from .forge/context.toml and keep the Issue ID and PR ID. Afterwards, frg ticket commands need FORGE_TICKET_ID.

text

frg config clear-ticket [OPTIONS]

Example

bash

frg config clear-ticket

`frg config user`

Set the user identity for OpenSearch reporting in .forge/context.toml. The identity survives frg config clear-context. Forge resolves the identity in this order: FORGE_USER_NAME/FORGE_USER_EMAIL, .forge/context.toml, Git user.name/user.email, the OS user name, then a descriptive fallback.

text

frg config user [OPTIONS] --email <EMAIL>

Option	Description	Values / default
`--name <NAME>`	User display name.
`--email <EMAIL>`	User email address. Required.

Example

bash

frg config user --name "Jane Doe" --email jane@example.com

`frg config show`

Display the complete configuration state: project, agent, toolchain, workflow context, lock status, customizations, and configuration sources. Read-only.

text

frg config show [OPTIONS]

Option	Description	Values / default
`-v, --verbose`	Show additional details, including file paths.	Flag
`--no-color`	Disable colored output. `NO_COLOR=1` has the same effect.	Flag

Example

bash

frg config show --verbose --no-color

`frg guide`

Open the Forge user guide in your browser. Utility command.

text

frg guide [OPTIONS] [SECTION] [COMMAND]

Argument	Description
`[SECTION]`	Guide section to open.

Example

bash

frg guide

`frg guide open`

Open user guide in browser.

text

frg guide open [OPTIONS]

Example

bash

frg guide open

`frg shell`

Manage shell integration. Utility command.

text

frg shell [OPTIONS] [COMMAND]

Subcommand	Description
`install`	Install shell completions
`uninstall`	Uninstall shell completions
`generate`	Generate completion script without installing

`frg shell install`

Install shell completions.

text

frg shell install [OPTIONS] <SHELL>

Argument	Description
`<SHELL>`	Shell to install for (bash, zsh, fish, powershell).

Option	Description	Values / default
`--manual`	Print manual installation instructions instead of installing.	Flag

Example

bash

frg shell install zsh

`frg shell uninstall`

Uninstall shell completions.

text

frg shell uninstall [OPTIONS] <SHELL>

Argument	Description
`<SHELL>`	Shell to uninstall from.

Example

bash

frg shell uninstall zsh

`frg shell generate`

Generate completion script without installing.

text

frg shell generate [OPTIONS] <SHELL>

Argument	Description
`<SHELL>`	Shell to generate for.

Example

bash

frg shell generate bash > frg.bash

`frg status`

Check frg configuration and agent status. Utility command.

text

frg status [OPTIONS]

Option	Description	Values / default
`-v, --verbose`	Show detailed diagnostic information.	Flag

Example

bash

frg status --verbose

`frg diagnose`

Collect diagnostic information and assess frg readiness. Utility command.

text

frg diagnose [OPTIONS]

Option	Description	Values / default
`--format <FORMAT>`	Output format.	`human`, `json`; Default: `human`
`--bundle`	Generate a support bundle archive (`.tar.gz`).	Flag
`-o, --output <PATH>`	Output path for the bundle.
`--include-traces`	Include trace files from the last 24 hours in the bundle.	Flag
`--include-logs`	Include log files from the last 24 hours in the bundle.	Flag
`-v, --verbose`	Include detailed file paths and timing information.	Flag

Example

bash

frg diagnose --bundle --include-logs --include-traces --output frg-support.tar.gz

`frg workflow`

Manage and execute user-defined stateful workflows from .forge/config/workflows/. Utility command.

text

frg workflow [OPTIONS] <COMMAND>

Subcommand	Description
`list`	List available stateful workflows
`run`	Execute a stateful workflow
`status`	Show status of running or paused workflows
`approve`	Submit an approval for a pending workflow
`reject`	Reject a pending workflow approval
`unlock`	Release the repository workflow lock
`graph`	Generate a Mermaid diagram of a workflow
`validate`	Validate a workflow definition without executing

`frg workflow list`

List available stateful workflows.

text

frg workflow list [OPTIONS]

Option	Description	Values / default
`-v, --verbose`	Show detailed workflow information.	Flag

Example

bash

frg workflow list

Example output:

text

Available Workflows
════════════════════

 code-to-review - Iterative code generation with review and auto-fix (built-in)
 issue-to-plan - Issue and requirements drafting with implementation planning (built-in)
 issue-to-pr - Complete issue-to-PR lifecycle with iterative code generation (built-in)
 issue-to-pr-lite - Lightweight issue-to-PR workflow with reduced approval gates (built-in)
 issue-to-review - Complete issue-to-code review lifecycle without PR creation (built-in)
 issue-to-review-lite - Lightweight issue-to-code review lifecycle without PR creation (built-in)
 pr-create-publish - Create PR if needed, then draft and publish description (built-in)
 pr-review-merge - Review PR, await approval, then merge (built-in)
 pr-to-merge - Handles PR creation, remediation and merging (built-in)
 ticket-to-response - Complete ticket triage and response workflow for support requests (built-in)

Use 'frg workflow list --verbose' for details.

`frg workflow run`

Execute a stateful workflow.

text

frg workflow run [OPTIONS] <name>

Argument	Description
`<name>`	Workflow name to execute. Omit it and pass `--auto` instead to let the routing classifier pick one.

Option	Description	Values / default
`--auto`	Classify the current issue context and select a workflow automatically, instead of naming one. Asks for interactive confirmation unless `--bypass-approvals` is also given. See Auto-Routing Issues to Workflows.	Flag, conflicts with `<name>`
`--start-from <STEP_NAME>`	Start from this state instead of the initial state, for example to recover an interrupted run. List valid names with `--list-states`.
`--bypass-approvals`	Skip approval gates (for CI and automation). With `--auto`, also accepts the classifier's top choice without a confirmation prompt.	Flag
`--dry-run`	Validate the workflow without executing it.	Flag
`-l, --list-states`	List all states with name, type, and description; the initial state is marked `*`, and workflow-author-recommended entry states are marked `[recommended start]`. Does not execute, lock, or validate context.	Flag

Example

bash

frg config set-issue 42
frg workflow run issue-to-pr --list-states
frg workflow run issue-to-pr --start-from plan_implementation
frg workflow run --auto --bypass-approvals

`frg workflow classify`

Classify the configured issue and print which workflow would be selected, without running anything. Not listed in frg workflow --help, but fully functional. See Auto-Routing Issues to Workflows for the full decision model and configuration.

Inline approvals: when frg workflow run is attached to an interactive terminal, approval gates can be approved or rejected directly in that terminal. Set FORGE_DISABLE_INLINE_APPROVAL=1 to suppress the inline prompt and use only frg workflow approve / frg workflow reject from another session.

Approvals console: when frg app runs in an interactive terminal, repositories blocked at an approval gate show their approval code in the status table and can be approved or rejected from the same terminal. Type h for the command list; a 2 approves repository 2, a all batch-approves everything currently pending (one email, one confirmation), and r 1,3 <reason> batch-rejects with a shared reason. Each repository is still resolved independently through the same validation and audit path as frg workflow approve / frg workflow reject, which remain available from another terminal at any time. Set FORGE_DISABLE_INLINE_APPROVAL=1 (or run with --quiet, piped output, or in CI) to disable the console and use the out-of-band commands only. See Resolving approval gates for full details.

Common Use Cases:

Executing multi-step automated workflows
Running pre-defined process flows
Automating complex task sequences
Discovering available workflow states for resumption

Example

bash

frg config set-issue 1080
frg workflow classify

`frg workflow status`

Show status of running or paused workflows.

text

frg workflow status [OPTIONS] [name]

Argument	Description
`[name]`	Workflow name (optional, shows all if omitted).

Option	Description	Values / default
`-d, --work-dir <WORK_DIR>`	Job directory to query. By default, Forge uses the configured issue, PR, or ticket context, then the current job directory, then the most recent job.
`-v, --verbose`	Show artifacts with file sizes and timestamps.	Flag

Example

bash

frg workflow status issue-to-pr --verbose

`frg workflow approve`

Approve a workflow that waits at an approval gate. Without options, show the pending approval.

text

frg workflow approve [OPTIONS]

Option	Description	Values / default
`-w, --workflow-id <ID>`	Workflow to approve. Optional when a workflow is running or only one approval is pending.
`-c, --code <CODE>`	Approval code (case-sensitive).
`-e, --email <EMAIL>`	Your email address, recorded in the audit trail.
`--list-all`	Show all approvals, pending and completed, with staleness detection.	Flag
`-d, --work-dir <WORK_DIR>`	Job directory to query for approvals.
`--resume-at <STATE_NAME>`	After approval, go to this state instead of the `on_success` state.

Example

bash

frg workflow approve --code ABC123 --email dev@example.com

`frg workflow reject`

Reject a pending approval so the workflow moves to its rejection state, for example to exit a code generation loop or cancel the workflow.

text

frg workflow reject [OPTIONS]

Option	Description	Values / default
`-w, --workflow-id <ID>`	Workflow to reject. Optional when a workflow is running or only one approval is pending.
`-c, --code <CODE>`	Approval code (case-sensitive).
`-e, --email <EMAIL>`	Your email address, recorded in the audit trail.
`-r, --reason <REASON>`	Reason for the rejection.
`-d, --work-dir <WORK_DIR>`	Job directory to query for approvals.
`--resume-at <STATE_NAME>`	After rejection, go to this state instead of the `on_failure` state.

Example

bash

frg workflow reject --code ABC123 --email dev@example.com --reason "Tests failing"

`frg workflow unlock`

Release the repository workflow lock left behind by an interrupted workflow. Only one workflow runs per repository at a time; use Git worktrees or separate clones to run workflows concurrently.

text

frg workflow unlock [OPTIONS]

Option	Description	Values / default
`-f, --force`	Release the lock even if it appears valid.	Flag

Example

bash

frg workflow unlock --force

`frg workflow graph`

Generate a Mermaid state diagram of a workflow. By default, Forge writes .forge/config/workflows/<workflow-name>.md.

text

frg workflow graph [OPTIONS] <name|--all>

Argument	Description
`[name]`	Workflow name to visualize.

Option	Description	Values / default
`-a, --all`	Generate diagrams for all workflows.	Flag
`-p, --print`	Print diagrams to stdout instead of writing files.	Flag

Example

bash

frg workflow graph issue-to-pr --print

`frg workflow validate`

Validate one workflow definition (TOML structure, required fields, state reachability, cycles, terminal states) without executing it. Needs no Issue or PR context.

text

frg workflow validate [OPTIONS] <name>

Argument	Description
`<name>`	Workflow name to validate.

Example

bash

frg workflow validate issue-to-pr

Example output:

text

✓ Workflow 'issue-to-pr' is valid

 Version: 2.0.0
 States: 38
 Source: built-in (<built-in>/issue-to-pr.toml)

Validation checks passed:
 ✓ Schema structure valid
 ✓ All states reachable from 'draft_issue'
 ✓ Terminal states reachable
 ✓ No direct self-loops detected
 ✓ Escape conditions valid

`frg learn`

Interactive tutorial system for learning frg through hands-on exercises. Utility command.

text

frg learn [OPTIONS] <COMMAND>

Subcommand	Description
`init`	Configure coding agent for tutorials
`list`	List all available tutorials
`run`	Run a specific tutorial
`next`	Run the next incomplete tutorial

Note: Workflow tutorials require a valid Telerik license.

`frg learn init`

Configure your coding agent for the tutorials (runs frg config init --agent <agent> --models stable) and extract the Forge documentation to .forge/docs/. Run it before other learn commands.

text

frg learn init [OPTIONS]

Example

bash

frg learn init

`frg learn list`

List all tutorials with name, ID, description, estimated duration, and completion status.

text

frg learn list [OPTIONS]

Example

bash

frg learn list

`frg learn run`

Run a tutorial by name or ID. Progress is tracked in .forge/config/learn.toml.

text

frg learn run [OPTIONS] <name>

Argument	Description
`<name>`	Tutorial name or ID to run.

Option	Description	Values / default
`-f, --force`	Skip the confirmation for a tutorial you already completed.	Flag

Example

bash

frg learn run ask-architecture

`frg learn next`

Run the next incomplete tutorial in sequence.

text

frg learn next [OPTIONS]

Example

bash

frg learn next

`frg app`

Run workflow operations across the repositories listed in application.toml. Utility command group.

text

frg app [OPTIONS] <COMMAND>

App operations run in one of two modes, set per operation by app_workflow in commands.toml:

Direct execution (default): one AI invocation with application context. Accepts the common workflow options.
Workflow execution: runs the configured workflow in each child repository through frg workflow run. Accepts only --start-from <STEP_NAME>, --bypass-approvals, --dry-run, and the operation's modifiers as plain flags. --model and --clear are not supported in this mode.

Note: --lite and --lite-edit appear in the help of some app operations, but Forge rejects them: "The --lite flag is not supported for frg app commands."

`frg app discover`

Find repositories whose project.toml sets allow_app to this application's UUID and save them to [[repositories]] in application.toml.

text

frg app discover [OPTIONS]

Option	Description	Values / default
`-f, --force`	Overwrite the existing `[[repositories]]` configuration in `application.toml`.	Flag
`--auto`	Generate `project.toml` with AI-populated metadata and `allow_app` for each discovered repository that has none. Shows an AI-content warning; set `FORGE_ACCEPT_AUTO_RISK=true` to bypass it in CI.	Flag

Note: Run frg app discover after you add allow_app to the project.toml of each repository.

Example

bash

FORGE_ACCEPT_AUTO_RISK=true frg app discover --auto

Disabling the role prompt

bash

frg issue draft --role none

none is a reserved value that omits the role (persona) prompt entirely, reducing input and cached token cost. It is accepted case-insensitively (--role NONE). All other unrecognised values are still rejected with an Invalid role error.

To disable roles persistently, see Command customization → Disabling role prompting.

Default Role Assignments

App-level issue operations.

text

frg app issue [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`draft`	Create a local issue draft. Use --lite for simple changes, --edit to customize with your instructions	Direct	`--edit [<INSTRUCTIONS>]`, `--lite`, `--lite-edit [<INSTRUCTIONS>]`
`publish`	Publish local draft to issue tracking system	Direct	—
`review`	Review issue for completeness and quality	Direct	`--edit [<INSTRUCTIONS>]`, `--lite`, `--lite-edit [<INSTRUCTIONS>]`
`plan`	Generate detailed implementation plan. Use --lite for simple features/bug fixes	Workflow	Common options not accepted. `--edit`, `--lite`, `--lite-edit`, `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`triage`	Evaluate and prioritize issue	Direct	—
`split`	Split large issue into smaller work items	Direct	—
`ask` `[QUESTION]`	Ask questions about current issue context	Direct	—

`frg app backlog`

App-level backlog operations.

text

frg app backlog [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`create`	Create strategic planning document	Direct	`--edit [<INSTRUCTIONS>]`
`review`	Review backlog health and quality	Direct	`--edit [<INSTRUCTIONS>]`
`rank`	Rank backlog items by priority	Direct	`--edit [<INSTRUCTIONS>]`
`ask` `[QUESTION]`	Ask questions about backlog strategy	Direct	—

`frg app code`

App-level code operations.

text

frg app code [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`create`	Generate new code	Workflow	Common options not accepted. `--fix`, `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`review`	Review code quality	Direct	`--edit [<INSTRUCTIONS>]`, `--lite`, `--lite-edit [<INSTRUCTIONS>]`, `--auto-fix <LEVEL>`
`refactor`	Restructure existing code	Direct	`--fix [<INSTRUCTIONS>]`
`document`	Generate code documentation	Direct	`--edit [<INSTRUCTIONS>]`
`build`	Compile and build code	Direct	—
`test`	Execute test suites	Direct	—
`ask` `[QUESTION]`	Ask questions about code	Direct	—

`frg app pr`

App-level pr operations.

text

frg app pr [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`draft`	Create pull request draft	Workflow	Common options not accepted. `--edit`, `--lite`, `--lite-edit`, `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`publish`	Publish pull request draft to GitHub	Workflow	Common options not accepted. `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`review`	Review pull request	Workflow	Common options not accepted. `--edit`, `--lite`, `--lite-edit`, `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`merge`	Analyze merge safety and prepare merge	Workflow	Common options not accepted. `--fix`, `--start-from <STEP_NAME>`, `--bypass-approvals`, `--dry-run`
`ask` `[QUESTION]`	Ask questions about pull request	Direct	—

`frg app docs`

App-level docs operations.

text

frg app docs [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`create`	Generate documentation or guides	Direct	`--edit [<INSTRUCTIONS>]`
`build`	Build documentation from code	Direct	`--dev`
`ask` `[QUESTION]`	Ask questions about documentation	Direct	—

`frg app ticket`

App-level ticket operations.

text

frg app ticket [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`triage`	Analyze ticket to determine severity and identify missing information	Direct	`--edit [<INSTRUCTIONS>]`
`respond`	Investigate root cause and generate comprehensive response	Direct	`--edit [<INSTRUCTIONS>]`
`ask` `[QUESTION]`	Ask questions about ticket context	Direct	—
`correlate`	Analyze patterns across multiple related tickets	Direct	—

`frg app sec`

App-level sec operations.

text

frg app sec [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`audit`	Audit project for security vulnerabilities using SAST findings	Direct	—
`patch`	Generate remediation patch for a specific security finding	Direct	`--edit [<INSTRUCTIONS>]`
`ask` `[QUESTION]`	Ask questions about security findings and remediation	Direct	—

`frg app ask`

App-level ask operations.

text

frg app ask [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`default`	Ask a question about the codebase without requiring issue context	Direct	—

`frg app run`

App-level run operations.

text

frg app run [OPTIONS] [COMMAND]

Operation	Description	Mode	Options beyond the common options
`default`	Run a task without requiring issue context	Direct	—

Example

bash

frg app code review --auto-fix critical
frg app issue plan --dry-run

`frg issue`

Work item planning and management. Workflow command (AI agent-driven).

text

frg issue [OPTIONS] [COMMAND]

Subcommand	Description
`draft`	Create a local issue draft. Use --lite for simple changes, --edit to customize with your instructions
`publish`	Publish local draft to issue tracking system
`review`	Review issue for completeness and quality
`plan`	Generate detailed implementation plan. Use --lite for simple features/bug fixes
`triage`	Evaluate and prioritize issue
`split`	Split large issue into smaller work items
`ask`	Ask questions about current issue context

`frg issue draft`

Create a local issue draft. Use --lite for simple changes, --edit to customize with your instructions.

text

frg issue draft [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Generate lightweight draft with essential details only (faster, minimal analysis).	Flag
`--lite-edit [<INSTRUCTIONS>]`	Lightweight draft with edit instructions (fast output + custom refinements). Pass instructions inline or in `lite-edit.md`.	Optional value

Example

bash

frg issue draft --lite-edit "Target the mobile checkout flow only"

`frg issue publish`

Publish local draft to issue tracking system.

text

frg issue publish [OPTIONS]

Options: the common workflow options only.

Example

bash

frg issue publish

`frg issue review`

Review issue for completeness and quality.

text

frg issue review [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Focused review on actionable items only (gaps, risks, recommendations). Excludes positive observations.	Flag
`--lite-edit [<INSTRUCTIONS>]`	Focused review with edit instructions (actionable items + custom refinements). Pass instructions inline or in `lite-edit.md`.	Optional value

Example

bash

frg config set-issue 42
frg issue review --lite

`frg issue plan`

Generate detailed implementation plan. Use --lite for simple features/bug fixes.

text

frg issue plan [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Generate lightweight plan with core essentials only (faster, single-phase, no diagrams).	Flag
`--lite-edit [<INSTRUCTIONS>]`	Lightweight plan with edit instructions (fast output + custom refinements). Pass instructions inline or in `lite-edit.md`.	Optional value

Example

bash

frg issue plan --context-file docs/architecture.md

`frg issue triage`

Evaluate and prioritize issue.

text

frg issue triage [OPTIONS]

Options: the common workflow options only.

Example

bash

frg issue triage

`frg issue split`

Split large issue into smaller work items.

text

frg issue split [OPTIONS]

Options: the common workflow options only.

Example

bash

frg issue split

`frg issue ask`

Ask questions about current issue context.

text

frg issue ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg issue ask "Which acceptance criteria are still ambiguous?"

`frg backlog`

Strategic planning and backlog management. Workflow command (AI agent-driven).

text

frg backlog [OPTIONS] [COMMAND]

Subcommand	Description
`create`	Create strategic planning document
`review`	Review backlog health and quality
`rank`	Rank backlog items by priority
`ask`	Ask questions about backlog strategy

`frg backlog create`

Create strategic planning document.

text

frg backlog create [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg backlog create --edit "Focus on Q3 platform work"

`frg backlog review`

Review backlog health and quality.

text

frg backlog review [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg backlog review

`frg backlog rank`

Rank backlog items by priority.

text

frg backlog rank [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg backlog rank

`frg backlog ask`

Ask questions about backlog strategy.

text

frg backlog ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg backlog ask "Which items block the release?"

`frg code`

Code and build operations. Workflow command (AI agent-driven).

text

frg code [OPTIONS] [COMMAND]

Subcommand	Description
`create`	Generate new code
`review`	Review code quality
`refactor`	Restructure existing code
`document`	Generate code documentation
`build`	Compile and build code
`test`	Execute test suites
`ask`	Ask questions about code

`frg code create`

Generate new code.

text

frg code create [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--fix [<INSTRUCTIONS>]`	Apply fix instructions during generation. Pass instructions inline or in `fix.md`.	Optional value

Example

bash

frg code create --agent github_copilot --model claude-sonnet-5

`frg code review`

Review code quality.

text

frg code review [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Focused review on critical issues only (bugs, security, breaking changes). Reduces token usage by 30-50%.	Flag
`--lite-edit [<INSTRUCTIONS>]`	Focused review with edit instructions (critical issues + custom refinements). Pass instructions inline or in `lite-edit.md`.	Optional value
`--auto-fix <LEVEL>`	Fix issues from the review automatically, by severity: `issues` (critical, major, minor), `critical`, `major` (critical and major), `minor` (critical, major, minor), `suggestions`, `all`.	`issues`, `critical`, `major`, `minor`, `suggestions`, `all`

--auto-fix works on the review output of the current job, so run frg code review before you use it.

Example

bash

frg code review --auto-fix critical

`frg code refactor`

Restructure existing code.

text

frg code refactor [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--fix [<INSTRUCTIONS>]`	Apply refactoring using your instructions. Pass instructions inline or in `fix.md`.	Optional value

Example

bash

frg code refactor --fix "Extract the shared validation logic"

`frg code document`

Generate code documentation.

text

frg code document [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg code document

`frg code build`

Compile and build code.

text

frg code build [OPTIONS]

Options: the common workflow options only.

Example

bash

frg code build --auto-retry

`frg code test`

Execute test suites.

text

frg code test [OPTIONS]

Options: the common workflow options only.

Example

bash

frg code test

`frg code ask`

Ask questions about code.

text

frg code ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg code ask "Where is user validation implemented?"

`frg pr`

Pull request operations. Workflow command (AI agent-driven).

text

frg pr [OPTIONS] [COMMAND]

Subcommand	Description
`draft`	Create pull request draft
`publish`	Publish pull request draft to GitHub
`review`	Review pull request
`merge`	Analyze merge safety and prepare merge
`ask`	Ask questions about pull request

`frg pr draft`

Create pull request draft.

text

frg pr draft [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Concise PR description with essential information only. Reduces token usage by 30-50%.	Flag
`--lite-edit [<INSTRUCTIONS>]`	Concise PR description with edit instructions. Pass instructions inline or in `lite-edit.md`.	Optional value

Example

bash

frg pr draft --lite

`frg pr publish`

Publish pull request draft to GitHub.

text

frg pr publish [OPTIONS]

Options: the common workflow options only.

Example

bash

frg pr publish

`frg pr review`

Review pull request.

text

frg pr review [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value
`--lite`	Actionable review feedback only (blocking issues, failing tests, conflicts). Single output file.	Flag
`--lite-edit [<INSTRUCTIONS>]`	Focused PR review with edit instructions. Pass instructions inline or in `lite-edit.md`.	Optional value

Example

bash

frg config set-pr 128
frg pr review --edit "Check error handling in the API layer"

`frg pr merge`

Analyze merge safety and prepare merge.

text

frg pr merge [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--fix [<INSTRUCTIONS>]`	Fix merge issues using your instructions. Pass instructions inline or in `fix.md`.	Optional value

Example

bash

frg pr merge --fix

`frg pr ask`

Ask questions about pull request.

text

frg pr ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg pr ask "Does this PR introduce breaking changes?"

`frg docs`

Project documentation and guides. Workflow command (AI agent-driven).

text

frg docs [OPTIONS] [COMMAND]

Subcommand	Description
`create`	Generate documentation or guides
`build`	Build documentation from code
`ask`	Ask questions about documentation

`frg docs create`

Generate documentation or guides.

text

frg docs create [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg docs create --role technical_writer

`frg docs build`

Build documentation from code.

text

frg docs build [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--dev`	Focus on a developer or API audience.	Flag

Example

bash

frg docs build --dev

`frg docs ask`

Ask questions about documentation.

text

frg docs ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg docs ask "Which APIs are undocumented?"

`frg ticket`

Customer support ticket investigation and response. Workflow command (AI agent-driven).

text

frg ticket [OPTIONS] [COMMAND]

Subcommand	Description
`triage`	Analyze ticket to determine severity and identify missing information
`respond`	Investigate root cause and generate comprehensive response
`ask`	Ask questions about ticket context
`correlate`	Analyze patterns across multiple related tickets

`frg ticket triage`

Analyze ticket to determine severity and identify missing information.

text

frg ticket triage [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg config set-ticket 123456
frg ticket triage

`frg ticket respond`

Investigate root cause and generate comprehensive response.

text

frg ticket respond [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg ticket respond --edit "Keep the response under 200 words"

`frg ticket ask`

Ask questions about ticket context.

text

frg ticket ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg ticket ask "Which release introduced this behavior?"

`frg ticket correlate`

Analyze patterns across multiple related tickets.

text

frg ticket correlate [OPTIONS]

Options: the common workflow options only.

Example

bash

frg ticket correlate

`frg sec`

Security scanning and vulnerability remediation. Workflow command (AI agent-driven).

text

frg sec [OPTIONS] [COMMAND]

Subcommand	Description
`audit`	Audit project for security vulnerabilities using SAST findings
`patch`	Generate remediation patch for a specific security finding
`ask`	Ask questions about security findings and remediation

`frg sec audit`

Audit project for security vulnerabilities using SAST findings.

text

frg sec audit [OPTIONS]

Options: the common workflow options only.

Example

bash

frg sec audit

`frg sec patch`

Generate remediation patch for a specific security finding.

text

frg sec patch [OPTIONS]

Options: the common workflow options, plus:

Option	Description	Values / default
`--edit [<INSTRUCTIONS>]`	Customize patch output with editing instructions. Pass instructions inline or in `edit.md`.	Optional value

Example

bash

frg sec patch --print-prompt

`frg sec ask`

Ask questions about security findings and remediation.

text

frg sec ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options only.

Example

bash

frg sec ask "Which findings affect the authentication module?"

`frg ask`

Ask a question about the codebase without Issue ID context. Forge reads question.md and writes answer.md in .forge/work/job_<id>/ask/ when an Issue ID is set, in .forge/work/ticket_<id>/ask/ when a Ticket ID is set, and in .forge/work/ask/ otherwise. Workflow command (AI agent-driven).

text

frg ask [OPTIONS] [QUESTION]

Argument	Description
`[QUESTION]`	Question to ask (or use question.md if not provided).

Options: the common workflow options, plus:

Option	Description	Values / default
`--tail`	Follow agent execution output in real time.	Flag

Example

bash

frg ask --context-file docs/architecture.md "Explain the caching strategy"

`frg run`

Execute a task that can modify files and run commands, without Issue context. Forge uses the fixed directory .forge/work/run/. Provide the task inline, with --task-file, or in .forge/work/run/task.md. Workflow command (AI agent-driven).

text

frg run [OPTIONS] [TASK]

Argument	Description
`[TASK]`	Task to execute (or use task.md / --task-file if not provided).

Options: the common workflow options, plus:

Option	Description	Values / default
`--task-file <FILE>`	Read the task from a plain text or Markdown file.
`--tail`	Follow agent execution output in real time.	Flag

Note: The frg run help lists only github_copilot and opencode for --agent. Its --auto-retry continues in the same agent session with a prompt that lists the missing files.

Example

bash

frg run --task-file improvements.md

Additional commands

`frg update`

Update Forge in place. The command comes with:

An include_prerelease setting that lets frg update install pre-release versions.
An auto_update setting, an update notice, and an auto-update hook.
A staged download that replaces the binary with an atomic swap.

|--------|-------------| | --dispatch-format | Write the plan in the flat format used for dispatch. | | --validate, --no-validate | Turn plan validation on or off. | | --summary | Print a plan summary. |

See frg backlog.

`frg telemetry`

Subcommand	Description
`status`	Show the telemetry configuration and consent status.
`on`	Enable telemetry data collection.
`off`	Disable telemetry data collection.
`test [--otel-only \| --opensearch-only]`	Test connectivity to the configured OTLP endpoint and OpenSearch; limit the test to one endpoint with an option.

Telemetry is on by default. To turn off usage telemetry, use either method: [usage]


See [Configuration Fields Reference](slug://configuration-fields-reference) and [Security Guide](slug://security-reference).

## See Also

- [Configuration Fields Reference](slug://configuration-fields-reference)
- [Environment Variables](slug://environment-variables-reference)
- [Workflow Schema Reference](slug://workflow-schema-reference)
- [Context Merging Reference](slug://context-merging-reference)
- [Command Structure](slug://cli-api-command-structure)