Utility Commands

Updated on Oct 5, 2026

Utility commands manage Forge itself: configuration, context, shell completions, diagnostics, stateful workflows, tutorials, and application discovery. This page lists each utility command once with its options. For full descriptions and more examples, see the Command Reference.

Most utility commands do not call your AI coding agent. The exceptions are frg config init --interactive, frg app discover --auto, frg learn run, and frg workflow run, which runs workflow steps.

Commands at a glance

Command	Purpose
frg config	Initialize, validate, lock, export, and inspect configuration; manage context
frg guide	Open the Forge user guide
frg shell	Install, uninstall, or generate shell completions
frg status	Check configuration and agent status
frg diagnose	Collect diagnostic information and create support bundles
frg workflow	Run and manage stateful workflows
frg learn	Interactive tutorials
frg app discover	Discover repositories for a multi-repository application

Every utility command accepts -q, --quiet (suppress all output except errors) and -h, --help.

config

config init

Initializes Forge configuration in the current repository.

bash

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

Option	Description	Default
-i, --interactive	Guides agent and model selection, AI-assisted project metadata review, tool integration setup, and final confirmation.
--app	Creates application.toml instead of a project configuration. Can be combined with --issues, --tickets, --scanner, --code, --agent, and --models.
--force	Overwrites the files selected by explicit options: --agent selects agents.toml; --issues, --tickets, or --scanner select toolchain.toml; --interactive selects project.toml. Cannot be used alone or with --app.
--issues <TOOL>	Issue tracker, for example github_issues, jira, azure_devops, shortcut, local.
--tickets <TOOL>	Ticket tracker, same values as --issues.
--code <TOOL>	Code platform, for example github, github_enterprise, bitbucket, azure_devops, local.
--scanner <TOOL>	Security scanner, for example polaris, github_sast.
--agent <AGENT>	AI coding agent: claude_code, github_copilot, opencode. Required to generate agents.toml.
--models <PROFILE>	Model profile: lite, balanced, stable, heavy.	stable

In non-interactive mode, Forge skips agent configuration unless you pass --agent; use --models to select a profile. See Model Selection for the profiles.

In interactive mode:

• Forge guides you through agent configuration, project metadata, toolchain integrations, and a final summary before it writes files.
• Press Enter to accept a default or AI suggestion, or enter a custom value where supported.
• An existing project.toml triggers Configuration already exists at .forge/config/project.toml. You can then edit the existing values field by field (keep, accept the AI suggestion, or enter a custom value) or cancel.
• name can have at most 100 characters and description at most 250. language, framework, testing_framework, and package_manager can each have at most 100 characters.
• Input must come from a terminal. Piped or empty stdin fails with Interactive mode requires user input. EOF detected - cannot proceed in non-interactive environment. In scripts, use explicit options such as --agent and --issues instead.

See Interactive Configuration, Project Configuration, and Hierarchical Configuration.

config validate

Validates configuration files.

bash

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

Option	Description	Default
-f, --file <FILE>	Validates a specific configuration file.	.forge/config/commands.toml

config lock

Validates project.toml, toolchain.toml, agents.toml, and commands.toml. If all pass, it writes .forge/.config_lock with the SHA-256 hash of each present file.

bash

frg config lock

When a lockfile exists and a configuration file changes, workflow commands are blocked until you run frg config lock again. Locking is opt-in: without a lockfile, workflow commands run without restriction.

config export

Exports built-in configuration to your project for customization. Specify at least one of the content options.

bash

frg config export --commands
frg config export --prompts --target issue
frg config export --workflows
frg config export --skills --scope=user
frg config export --security
frg config export --all --force

Option	Exports to	Description
--commands	.forge/config/commands.toml	Commented template of the command configuration.
--prompts	.forge/prompts/	Role and task prompt files.
--workflows	.forge/config/workflows/	Built-in workflow files.
--skills	.agents/skills/	Built-in SKILL.md files.
--security	.forge/config/.prompt-safety.toml	Prompt-injection detection rules.
--all		Exports commands, prompts, and workflows. Does not include skills or security configs.
-t, --target <TARGET>		Exports only one workflow target.
--scope <SCOPE>		Skill export scope: project (<repo>/.agents/skills/) or user (~/.agents/skills/). By default, user if the configuration comes from ~/.config/forge/, otherwise project.
--force		Overwrites existing files.

Warning: --force overwrites your customizations. Commit or back up exported files first.

When an exported skill already exists and the embedded version differs, Forge reports Skill updates available:. Run frg config export --skills --force to update.

Workflows in .forge/config/workflows/ override built-in workflows of the same name. The built-in workflows are issue-to-plan, issue-to-pr, issue-to-review, issue-to-review-lite, code-to-review, pr-create-publish, pr-review-merge, pr-to-merge, and ticket-to-response.

See Agent Skills and Prompt Safety.

Context commands

Context values are stored in .forge/context.toml and used by workflow commands.

Command	Description
frg config set-issue <ISSUE_ID>	Sets the current issue ID, for example 123, PROJ-456, AB#789.
frg config set-pr <PR_ID>	Sets the current GitHub pull request number.
frg config set-ticket <TICKET_ID>	Sets the current ticket ID, for example 123456, INC0012345, TICKET-42.
frg config set-service <SERVICE_NAME>	Selects a service in a monorepo configuration.
frg config show-context	Shows the current issue ID and PR ID and their source (environment variable or config file).
frg config clear-context	Removes the issue ID and PR ID.
frg config clear-issue	Removes the issue ID and keeps the PR ID.
frg config clear-pr	Removes the PR ID and keeps the issue ID.
frg config clear-ticket	Removes the ticket ID and keeps the issue ID and PR ID.
frg config clear-service	Removes the service selection.

The clear-* commands do not unset environment variables. Unset FORGE_ISSUE_ID, FORGE_PR_ID, or FORGE_TICKET_ID yourself.

bash

frg config set-issue 42
frg config show-context
frg config clear-context

See Context Sources.

config user

Sets the user identity for OpenSearch enterprise reporting. The identity is stored in .forge/context.toml and persists across frg config clear-context.

bash

frg config user --name "Jane Smith" --email "[e-mail]"
frg config user --email "[e-mail]"

Option	Description
--email <EMAIL>	User email address. Required.
--name <NAME>	User display name.

Forge resolves the identity in this order:

1. The FORGE_USER_NAME and FORGE_USER_EMAIL environment variables.
2. .forge/context.toml (this command).
3. Git config (user.name, user.email).
4. The operating-system user name.
5. A descriptive fallback.

In CI, set the environment variables:

bash

export FORGE_USER_NAME="CI Bot"
export FORGE_USER_EMAIL="[e-mail]"

See OpenSearch Integration.

config show

Displays the full configuration state: project settings, agent configuration, toolchain integration, execution context, and customizations. This command is read-only.

bash

frg config show
frg config show --verbose
NO_COLOR=1 frg config show

Option	Description
-v, --verbose	Shows file paths and additional details.
--no-color	Disables colored output. Output is also plain when piped.

guide

Opens the Forge user guide in your browser. Forge extracts the documentation embedded in the binary to a cache directory and opens it locally. The published guide is at https://www.telerik.com/forge/documentation.

bash

frg guide
frg guide open
frg guide <SECTION>

Argument or subcommand	Description
[SECTION]	Guide section to open.
open	Opens the user guide in the browser.

shell

Manages shell completions. Supported shells: bash, zsh, fish, powershell.

bash

frg shell install zsh
frg shell install bash --manual
frg shell uninstall zsh
frg shell generate fish > frg.fish

Subcommand	Description	Options
install <SHELL>	Installs completions in your shell profile.	--manual: shows manual installation instructions instead of changing the profile.
uninstall <SHELL>	Removes the completions that install added.
generate <SHELL>	Prints the completion script without installing it.

frg shell install updates the profile for your shell (~/.bashrc or ~/.bash_profile, ~/.zshrc, ~/.config/fish/config.fish, or the PowerShell Microsoft.PowerShell_profile.ps1). It creates a timestamped backup first and marks the added block with # Forge CLI completions (added by frg shell install). Restart your shell afterward.

See Shell Completions.

status

Checks the detected project root, Forge initialization, the default coding agent and its authentication, and the toolchain configuration.

bash

frg status
frg status --verbose

Option	Description
-v, --verbose	Shows detailed diagnostic information, including configuration warnings.

See AI Coding Agent Troubleshooting.

diagnose

Collects diagnostic information and assesses whether Forge is ready to run. Use --bundle to create an archive for support.

bash

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

Option	Description	Default
--format <FORMAT>	Output format: human or json.	human
--bundle	Generates a support bundle archive (.tar.gz).
-o, --output <PATH>	Output path for the bundle.
--include-traces	Includes trace files from the last 24 hours.
--include-logs	Includes log files from the last 24 hours.
-v, --verbose	Includes detailed file paths and timing information.

--format json and --bundle are mutually exclusive. Review bundle contents before you share them.

See Diagnostic Command.

workflow

Manages user-defined stateful workflows: TOML-defined multi-step sequences in .forge/config/workflows/ that combine commands, steps, and approval gates. Only one workflow can run in a repository at a time.

bash

frg workflow list
frg workflow run issue-to-pr --dry-run
frg workflow run issue-to-pr --list-states
frg workflow run issue-to-pr --start-from <STEP_NAME>
frg workflow status
frg workflow approve --code ABC --email [e-mail]
frg workflow reject --code ABC --email [e-mail] --reason "Tests failing"
frg workflow graph issue-to-pr --print
frg workflow validate my-custom-flow
frg workflow unlock

Subcommand	Description	Options
list	Lists available workflows.	-v, --verbose
run <name>	Executes a workflow.	--start-from <STEP_NAME>, --bypass-approvals, --dry-run, -l, --list-states
status [name]	Shows running or paused workflows.	-d, --work-dir <WORK_DIR>, -v, --verbose
approve	Approves a workflow waiting at an approval gate. Without arguments, shows the pending approval.	-w, --workflow-id <ID>, -c, --code <CODE>, -e, --email <EMAIL>, --list-all, -d, --work-dir <WORK_DIR>, --resume-at <STATE_NAME>
reject	Rejects an approval gate and moves to the rejection state.	-w, --workflow-id <ID>, -c, --code <CODE>, -e, --email <EMAIL>, -r, --reason <REASON>, -d, --work-dir <WORK_DIR>, --resume-at <STATE_NAME>
unlock	Releases the repository workflow lock after an interruption.	-f, --force
graph <name>	Writes a Mermaid state diagram to .forge/config/workflows/<name>.md.	-a, --all, -p, --print
validate <name>	Validates a workflow definition (structure, state reachability, cycles, terminal states) without executing. No FORGE_ISSUE_ID or FORGE_PR_ID is needed.

Approval codes are case-sensitive. The workflow ID is optional when a workflow is running or only one approval is pending.

Warning: Run frg workflow unlock only when no other workflow is running. To run workflows concurrently, use Git worktrees or separate repository folders.

See Stateful Workflows and Workflow Schema.

learn

Runs interactive tutorials on the healthcare-app-angular demo application. Workflow tutorials require a valid Telerik license.

bash

git clone https://github.com/telerik/healthcare-app-angular
cd healthcare-app-angular
frg learn init
frg learn list
frg learn next
frg learn run ask-architecture

Subcommand	Description	Options
init	Selects your coding agent, runs frg config init --agent <agent> --models stable, and extracts the documentation to .forge/docs/. Run this first.
list	Lists tutorials with description, estimated duration, and completion status.
run <name>	Runs a tutorial by name or ID.	-f, --force: skips the confirmation for completed tutorials.
next	Runs the next incomplete tutorial.

Progress is tracked in .forge/config/learn.toml. The seven tutorials cover architecture overview, developer guide, RFA investigation, issue resolution, code refactoring, security review, and backlog creation.

See Licensing.

app discover

Finds repositories whose project.toml has an allow_app value that matches the application UUID. The results are saved to the [[repositories]] section of application.toml.

bash

frg app discover
frg app discover --force
frg app discover --auto
FORGE_ACCEPT_AUTO_RISK=true frg app discover --auto

Option	Description
-f, --force	Overwrites the existing repositories configuration in application.toml.
--auto	Uses AI to generate project.toml for discovered child repositories that lack one, and sets allow_app. Skips repositories that already have a project.toml. Shows a warning first; set FORGE_ACCEPT_AUTO_RISK=true to bypass it in CI.

For the other frg app commands, see Command Structure.

Additional commands

update

frg update updates Forge to the latest version. See Update Command.

telemetry

Telemetry is on by default. To opt out, use either method:

• Set the environment variable FORGE_TELEMETRY_DISABLED=1.
• Add this to telemetry.toml (.forge/config/telemetry.toml, ~/.config/forge/telemetry.toml, or the path in FORGE_TELEMETRY_PATH):

toml

[usage]
enabled = false

See Environment Variables and Security.

See Also

• Command Structure
• Workflow Commands
• Command Reference
• Configuration Overview