!cmd in an interactive session to run a shell command without spending a model turn. !!cmd also attaches the output as context for your next message.
Quick Start
1
Enable the gate and run a command
Shell escape is off by default. Enable it, launch a session, and run a command inline:The command runs immediately and prints its output — no model turn is spent.
2
Attach output as context
Prefix with The follow-up turn sees the diff, prefixed as
!! to also stash the output as context for your next message:[shell output].How It Works
The!cmd path never calls the model — agent.start() only fires on your next real prompt, prefixed with [shell output] if a !!cmd is pending.
!cmd vs !!cmd
Pick ! for a quick peek and !! when you want the model to read the output.
Configuration
Shell escape reuses the same gate that powers!`cmd` template substitution — there is no second flag to remember.
- Environment variable
- Config file
The environment variable wins if set to a truthy value; otherwise the
commands.allow_shell config flag is consulted. When neither is set, typing !ls prints a one-line enable hint and never runs the command.Safety Limits
Shell escape carries the same safety posture as!`cmd` template substitution.
Failure Behaviour
A non-zero exit, timeout, or output cap never raises into the REPL loop — the diagnostic is rendered inline instead. For!!cmd, the error text is still attached as context so the model can help debug it.
Pending-Context Lifecycle
!!cmd output is retained until the next model call succeeds. If that call raises, the context stays so you can retry without re-running the command.
Common Patterns
Review a staged diff with the model:Best Practices
Keep the gate off for unattended surfaces
Keep the gate off for unattended surfaces
Bots and webhooks that never need a shell should leave
PRAISONAI_ALLOW_SHELL unset. Default-off keeps unattended surfaces shell-free.Prefer !!cmd for context you actually want the model to read
Prefer !!cmd for context you actually want the model to read
Attaching everything bloats prompts. Use
! for a quick look and reserve !! for output the model needs.Combine with @file mentions
Combine with @file mentions
Pair shell escape with
@file mentions to give the model both live output and file content in one turn. See the @file mentions docs.Beware the 100 KB cap for verbose commands
Beware the 100 KB cap for verbose commands
Output is capped at 100 KB. Pipe noisy commands through
head, tail, or grep first to keep the useful lines.Related
Interactive TUI
The full interactive terminal interface, including
@file mentions.Slash Commands
Registered
/cmd commands — a sibling input path to !cmd.Custom Agents & Commands
The sibling
!`cmd` template substitution — same gate.