forge

Main Forge command and global flags

The forge command is the main entry point for the Forge CLI. When run without arguments, it starts an interactive AI-enhanced terminal session.

Usage

forge [FLAGS] [OPTIONS] [SUBCOMMAND]

Interactive Mode

Start an interactive session:

forge

The session starts in interactive mode when no prompt, piped input, or subcommand is provided.

Global Flags

--prompt · string · default: "none"

Direct prompt to process without entering interactive mode. When provided, executes a single command and exits.

Alias: -p

forge -p "List all files in the current directory"
forge --prompt "Explain this error message"

Supports prompts with leading hyphens:

forge -p "- hi"
forge -p "--something"

--conversation · path · default: "none"

Path to a JSON file containing the conversation to execute.

forge --conversation ./conversation.json

--conversation-id · uuid · default: "none"

Conversation ID to use for this session. When provided, resumes or continues an existing conversation instead of generating a new ID.

Alias: --cid

forge --cid 550e8400-e29b-41d4-a716-446655440000
forge --conversation-id 550e8400-e29b-41d4-a716-446655440000

--directory · path · default: "none"

Working directory to use before starting the session. When provided, changes to this directory before starting forge.

Alias: -C

forge -C ~/projects/myapp
forge --directory /path/to/project

--sandbox · string · default: "none"

Name for an isolated git worktree to create for experimentation.

forge --sandbox experiment-1

--verbose · boolean · default: "false"

Enable verbose logging output.

forge --verbose

--restricted · boolean · default: "false"

Use restricted shell (rbash) for enhanced security.

Alias: -r

forge -r
forge --restricted

--agent · string · default: "none"

Agent ID to use for this session.

Alias: --aid

forge --agent sage
forge --aid muse

--model · string · default: "none"

Override the model to use for this session. This is a runtime override and does not change the permanent configuration.

forge --model anthropic/claude-sonnet-4
forge --model openai/gpt-4

--provider · string · default: "none"

Override the provider to use for this session. This is a runtime override and does not change the permanent configuration.

forge --provider OpenAI
forge --provider Anthropic

--workflow · path · default: "none"

Path to a file containing the workflow to execute.

Alias: -w

forge -w ./workflow.yaml
forge --workflow /path/to/workflow.yaml

--event · json · default: "none"

Event to dispatch to the workflow in JSON format.

Alias: -e

forge -w workflow.yaml -e '{"type": "start", "data": {}}'

Examples

One-Shot Commands

Execute a single command without interactive mode:

forge -p "What are the recent changes in this repo?"

Piped Input

Pipe content to forge:

cat error.log | forge
echo "Explain this code" | forge

Resume Conversation

Continue an existing conversation:

forge --cid 550e8400-e29b-41d4-a716-446655440000

Change Directory

Start forge in a specific directory:

forge -C ~/projects/webapp -p "Show me the main entry point"

Use Specific Agent

Start with a specific agent:

forge --agent sage
forge --aid muse -p "Help me write documentation"

Override Model

Use a different model for this session:

forge --model anthropic/claude-sonnet-4

Output

Forge provides rich terminal output with:

• Syntax-highlighted code blocks
• Markdown rendering
• Progress indicators for long-running operations
• Interactive prompts and menus

Exit Codes

• 0 - Successful execution
• 1 - General error
• 2 - Command line parsing error