Skip to main content

Using Forge

This guide covers everything you need to know about using Forge effectively, from initial setup to making the most of its shell integration features.

Setting Up API Credentials​

After installing Forge, you need to configure it to work with your preferred AI provider:

  1. Create a .env file in your home directory:
touch ~/.env
  1. Open the .env file and add your API key. Here's an example using Open Router (recommended):
# Your API key for accessing AI models
OPENROUTER_API_KEY=<Enter your Open Router Key>

You can get an API key at Open Router.

Supported AI Providers​

Forge automatically detects API keys from your environment variables in this priority order:

  1. FORGE_KEY - Antinomy's provider (OpenAI-compatible)
  2. OPENROUTER_API_KEY - Open Router provider (aggregates multiple models)
  3. OPENAI_API_KEY - Official OpenAI provider
  4. ANTHROPIC_API_KEY - Official Anthropic provider

To use a specific provider, set the corresponding variable in your .env file:

# Examples of different provider configurations (use only one)

# For Open Router (recommended, provides access to multiple models)
OPENROUTER_API_KEY=your_openrouter_key_here

# For official OpenAI
OPENAI_API_KEY=your_openai_key_here

# For official Anthropic
ANTHROPIC_API_KEY=your_anthropic_key_here

# For Antinomy's provider
FORGE_KEY=your_forge_key_here

Starting Forge​

Once you've set up your API credentials, start Forge by typing:

forge

This launches Forge in its default configuration with a prompt ready for your instructions.

Basic Workflow​

Using Forge follows this simple pattern:

  1. Start Forge in your project directory
  2. Type your task in natural language (e.g., "Create a React component for a login form")
  3. Review the proposed changes and output
  4. Continue the conversation to refine, clarify, or extend the solution

Shell Integration Features​

Forge enhances your terminal experience with several powerful features:

Intelligent Autocomplete​

File and Path Completion​

Type @ followed by a partial path and press Tab to get contextual path completion:

# Type this and press Tab to complete file paths
@src/com

This will complete to matching paths like @src/components/ or @src/common/.

Command History Navigation​

Access your command history efficiently:

  • Right Arrow: Complete previously executed commands
  • Up Arrow: Navigate through command history
  • Ctrl+R: Search through command history

Example of history search:

(reverse-i-search)`git`: git commit -m "Fix login bug"

WYSIWYG Shell Experience​

Forge visualizes each executed command with colorful formatting, displaying command outputs just as if you were typing them directly in your terminal. This ensures clarity and enhances interaction, making commands and their results clearly visible.

Command Control​

Stay in control of your shell environment:

  • Cancel operations: Press Ctrl+C to gracefully interrupt ongoing operations
  • Exit Forge: Press Ctrl+D to exit the shell session

Using Commands​

Forge provides several built-in commands prefixed with a forward slash (/):

  • /new: Start a new task (clears context)
  • /act: Switch to ACT mode (implements changes)
  • /plan: Switch to PLAN mode (plans but doesn't implement changes)
  • /info: View environment summary
  • /models: List available AI models
  • /help: Display help information
  • /dump: Save conversation for debugging
  • /exit: Exit Forge

For example, to switch to planning mode:

/plan

For a complete list of commands and their usage, see the Commands documentation.

Effective Usage Patterns​

To get the most out of Forge, keep these patterns in mind:

Clear Communication​

  • Be specific about what you want Forge to do
  • Provide context when asking for complex tasks
  • Use references to specific files or functions when relevant

Project Context​

Start Forge from your project's root directory to give it the full context of your project structure.

Troubleshooting​

If you encounter issues:

  • Check your API key in the .env file
  • Verify internet connectivity for API access
  • Review logs by running /info to find log file locations
  • Use /dump to save the conversation context for debugging

Next Steps​

Now that you're familiar with using Forge, you might want to explore: