Skip to main content

Custom Commands

Forge allows you to define and use custom commands that extend its functionality and streamline your workflow. These commands can be executed within the Forge CLI using the /command_name syntax and are defined as individual files in the ~/forge/commands/ directory.

What Are Custom Commands?​

Custom commands are user-defined shortcuts that trigger specific actions or workflows. They enable you to:

  • Create project-specific automation
  • Standardize common workflows across your team
  • Simplify complex operations into single commands
  • Integrate Forge with your development processes

Defining Custom Commands​

Custom commands are defined as individual Markdown files in the ~/forge/commands/ directory. Each command file follows the naming convention command-name.md.

Command File Structure​

Create a Markdown file in ~/forge/commands/ with frontmatter containing metadata and the body containing the prompt:

~/forge/commands/check.md

---
name: check
description: Checks if the code is ready to be committed
---

- Run the `lint` and `test` commands and verify if everything is fine.
  <lint>npm run lint</lint>
  <test>npm test</test>
- Fix every issue found in the process

File Format​

Command files use Markdown with YAML frontmatter:

  • Frontmatter: Contains name and description fields enclosed in ---
  • Body: The content after frontmatter becomes the default prompt for the command

Configuration Options​

OptionRequiredLocationDescription
nameYesFrontmatterThe name of the command (used as /name in the CLI)
descriptionYesFrontmatterA description of what the command does (shown in help)
promptNoBodyDefault prompt value used when no arguments are provided
Deprecated: Commands in forge.yaml

Defining commands in the commands section of forge.yaml is deprecated and no longer supported. Please migrate your commands to individual Markdown files in the ~/forge/commands/ directory.

Using Custom Commands​

Once configured, you can use custom commands in the Forge CLI in two ways:

Basic Command Execution​

To execute a command with its default value (if provided):

/fmt

This executes the fmt command with the default instructions defined in its prompt.

Command with Arguments​

Commands can accept arguments passed after the command name:

/explain React useEffect lifecycle
/branch feature/user-authentication
/refactor UserService to improve performance

All arguments are combined into a single text value that becomes part of your command's instruction.

Working with Command Arguments​

Commands can use the {{parameters}} variable to incorporate user-provided arguments into their prompts. This makes commands flexible and reusable across different contexts.

Static Commands​

Commands without parameters have fixed prompts:

~/forge/commands/review.md

---
name: review
description: Review code for bugs and improvements
---

Review the code for bugs, security issues, performance problems, and suggest improvements

Usage: /review

Dynamic Commands​

Commands that accept arguments use {{parameters}} to insert user input:

~/forge/commands/explain.md

---
name: explain
description: Explain code or concepts in detail
---

Provide a detailed explanation of: {{parameters}}

Include:

- Purpose and functionality
- How it works internally
- Common use cases and examples
- Best practices and gotchas

Usage: /explain React hooks and their lifecycle

The {{parameters}} placeholder will be replaced with react hooks and their lifecycle.

Conditional Parameters​

Use Handlebars conditionals for commands that work with or without arguments:

~/forge/commands/test.md

---
name: test
description: Generate unit tests
---

Generate comprehensive unit tests{{#if parameters}} for {{parameters}}{{/if}}.

Include edge cases, error handling, and integration scenarios.

Usage:

  • /test → Generates tests for current context
  • /test UserService → Generates tests specifically for UserService
tip

Use {{parameters}} anywhere in your command prompt where you want to insert user-provided arguments.

Example Custom Commands​

Git Workflow Commands​

~/forge/commands/pr.md

---
name: pr
description: Create a pull request description
---

Create a detailed pull request with the title: {{parameters}}

Include:

- Summary of changes
- Related issue numbers
- Testing performed
- Breaking changes (if any)

Usage: /pr Add OAuth2 authentication

~/forge/commands/refactor.md

---
name: refactor
description: Refactor code with specific focus
---

Refactor the following: {{parameters}}

Goals:

- Improve readability and maintainability
- Enhance performance
- Follow best practices
- Maintain existing functionality

Usage: /refactor authentication module in src/auth

Development Workflow Commands​

~/forge/commands/document.md

---
name: document
description: Generate documentation for a file
---

Generate comprehensive documentation for the specified code

Project-Specific Commands​

~/forge/commands/fixme.md

---
name: fixme
description: Looks for all the fixme comments in the code and attempts to fix them
---

Find all the FIXME comments in source-code files and attempt to fix them.

~/forge/commands/deploy.md

---
name: deploy
description: Prepare deployment package and update version numbers
---

Update version numbers and prepare the project for deployment

Best Practices​

  1. Descriptive Names: Use clear, action-oriented names for commands (use lowercase with hyphens for multi-word commands)
  2. Helpful Descriptions: Write descriptions that explain both the purpose and expected outcome
  3. Use Parameters: Make commands flexible with {{parameters}} for user input
  4. Clear Instructions: Provide detailed steps in command prompts for consistent results
  5. Specialized Agents: Configure agents specifically for handling particular commands in ~/forge/agents/
  6. File Organization: Keep command files organized in ~/forge/commands/ with descriptive filenames
  7. Documentation: Document custom commands for your team in a project README

Migrating from forge.yaml​

If you have commands defined in your forge.yaml file, migrate them to individual Markdown files:

Old format (deprecated):

# forge.yaml
commands:
  - name: fmt
    description: Format and fix Rust code
    prompt: |
      Run cargo fmt and cargo clippy, then fix any issues

New format:

In ~/forge/commands/fmt.md

---
name: fmt
description: Format and fix Rust code
---

Run cargo fmt and cargo clippy, then fix any issues

Migration Steps​

  1. Create the ~/forge/commands/ directory if it doesn't exist:

    mkdir -p ~/forge/commands

  2. For each command in your forge.yaml, create a Markdown file:

    # Example: converting a fmt command
    touch ~/forge/commands/fmt.md

  3. Add the frontmatter with name and description fields

  4. Add the prompt as the body content (without prompt: prefix)

  5. Remove the commands section from your forge.yaml

  6. Restart Forge to load the new command definitions