Shell Commands

Forge allows you to execute native shell commands directly from the CLI by prefixing them with ! without switching context. These commands are executed immediately without being processed by the AI, providing a fast way to run system operations without leaving the Forge environment.

Direct Execution

Commands that start with ! bypass the AI and are executed directly in your shell. This ensures immediate execution and allows you to seamlessly integrate shell operations into your Forge workflow.

Usage

To execute a shell command, prefix it with !:

! ls -la
! git status
! npm install
! python script.py
! mkdir new-directory

These commands will be executed in your current working directory, and their output will be displayed in the console.

Gotchas

Shell Compatibility

ZSH and PowerShell don't work out of the box with Forge's shell command execution. Forge uses a restricted bash environment for security and consistency across platforms. If you're using ZSH or PowerShell as your default shell, some shell-specific features, aliases, and functions will not be available when executing commands through Forge.

Workaround: Use standard POSIX-compliant commands or explicitly call your preferred shell:

! zsh -c "your-zsh-specific-command"
! powershell -c "Your-PowerShell-Command"

Stateless Execution

All commands are executed fresh without carrying forward information between runs. Each shell command starts with a clean environment, meaning:

• Environment variables set in one command won't persist to the next.
• Background processes started in one command won't be accessible in subsequent commands.
• Shell history and session state are not maintained.

Example of what won't work:

! export MY_VAR="hello"
! echo $MY_VAR # This will be empty

Workaround: Combine related commands in a single execution:

! export MY_VAR="hello" && echo $MY_VAR

Directory Changes Don't Persist

Changing the directory will only be applicable until the command executes and will not affect Forge's working directory. The cd command or any directory navigation within a shell command is temporary and isolated to that specific command execution.

Example:

! cd /tmp
! pwd # This will still show your original working directory

Workaround: To change Forge's working directory for a session, restart Forge in your target directory:

1. Exit and navigate:

   # Exit Forge, then:
   cd /path/to/project
   forge

2. Or restart with path directly:

   forge /path/to/project

Alternative approach:

• Chain commands with directory changes:

  ! cd /tmp && ls -la                  # Execute ls in /tmp
  ! cd /path/to/project && npm install # Install dependencies in specific directory

Purpose of Shell Commands

The ! shortcut is for quick command execution without context switching, not as a replacement for your preferred shell environment. For complex shell workflows, interactive sessions, or shell-specific features, continue using your native ZSH, PowerShell, or bash terminal alongside Forge.

Platform Considerations

The available shell commands depend on your operating system:

• macOS/Linux: Full bash command support.
• Windows: Command Prompt commands.

Make sure to use commands appropriate for your platform when sharing Forge sessions or documentation.