Skip to main content

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, or 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 have no bearing on 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 permanently change Forge's working directory, you need to exit Forge, navigate to your preferred directory, and start Forge again in that location. Alternatively, use absolute paths or combine directory changes with your commands:

! 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 designed for quick execution of individual commands 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.