Skip to main content
The terminal tool provides persistent command-line access with state preservation between commands. Environment variables, current directory, and running processes persist across multiple tool calls.

​
Key Features

  • Persistent Sessions: State maintained between commands
  • Multiple Sessions: Run concurrent terminal sessions
  • Long-Running Commands: Support for background processes
  • Interactive Process Support: Send input to running processes
  • Special Key Support: Full control sequences (Ctrl+C, arrow keys, etc.)
  • Working Directory Tracking: Automatic tracking of current directory

​
Parameters

​
command
string
required
The bash command to execute. Can be empty to check output of running commands (will wait for timeout period to collect output).Supported special keys and sequences (based on tmux key names):
  • Control sequences: C-c, C-d, C-z, C-a, C-e, C-k, C-l, C-u, C-w, etc.
  • Navigation keys: Up, Down, Left, Right, Home, End
  • Page keys: PageUp, PageDown, PgUp, PgDn
  • Function keys: F1-F12
  • Special keys: Enter, Escape, Space, Tab, BTab, BSpace, DC, IC
  • Meta/Alt sequences: M-key (e.g., M-f, M-b)
  • Shift sequences: S-key (e.g., S-F6, S-Tab)
Special keys work automatically - no need to set is_input=true.
​
is_input
boolean
default:"false"
If true, the command is sent as input to a currently running process. If false, the command is executed as a new bash command.Note: Special keys (C-c, C-d, etc.) automatically work when a process is running - you don’t need to set is_input=true for them. Use is_input=true for regular text input to running processes.
​
timeout
number
default:"30"
Optional timeout in seconds for command execution. CAPPED AT 60 SECONDS. If not provided, uses default wait (30s). On timeout, the command keeps running and the tool returns with status ‘running’.
​
terminal_id
string
default:"default"
Identifier for the terminal session. Use different IDs to manage multiple concurrent terminal sessions.
​
no_enter
boolean
default:"false"
If true, don’t automatically add Enter/newline after the command. Useful for:
  • Interactive prompts where you want to send keys without submitting
  • Navigation keys in full-screen applications
  • Multi-step commands

​
Response

​
content
string
Command output
​
exit_code
number
Exit code of the command (only for completed commands)
​
command
string
The executed command
​
terminal_id
string
The terminal session ID
​
status
string
Command status: ‘completed’ or ‘running’
​
working_dir
string
Current working directory after command execution

​
Examples

​
Basic Commands

# Execute a simple command
terminal_execute(
    command="ls -la"
)

# Multiple commands in sequence
terminal_execute(
    command="""cd /workspace
pwd
ls -la"""
)

# Run with custom timeout
terminal_execute(
    command="npm install",
    timeout=60
)

​
Long-Running Commands

# Start a background service
terminal_execute(
    command="python app.py > server.log 2>&1 &"
)

# Check progress of running command
terminal_execute(
    command="",
    timeout=5
)

# Interrupt a running process
terminal_execute(
    command="C-c"
)

​
Interactive Processes

# Start Python REPL
terminal_execute(
    command="python3"
)

# Send input to Python REPL
terminal_execute(
    command="print('Hello World')",
    is_input=True
)

# Send Escape key
terminal_execute(
    command="Escape",
    is_input=True
)

​
Multiple Terminal Sessions

# Start a Python session
terminal_execute(
    command="python3",
    terminal_id="python_session"
)

# Send input to Python REPL in specific session
terminal_execute(
    command="print('Hello World')",
    is_input=True,
    terminal_id="python_session"
)

# Use default session for other work
terminal_execute(
    command="ls -la",
    terminal_id="default"
)

​
Vim Navigation

# Open file in vim
terminal_execute(
    command="vim file.txt"
)

# Go to top (no enter needed)
terminal_execute(
    command="gg",
    is_input=True,
    no_enter=True
)

# Move down 5 lines
terminal_execute(
    command="5j",
    is_input=True,
    no_enter=True
)

# Enter insert mode
terminal_execute(
    command="i",
    is_input=True,
    no_enter=True
)

​
Important Notes

Command Execution: Avoid long pipelines and complex bash scripts. Break complex operations into multiple simple tool calls for clarity and debugging.
Timeout Behavior: Commands are NEVER killed on timeout - they keep running in background. Timeout only controls how long to wait before returning current output.

​
Best Practices

  1. Persistent Session: Environment variables, current directory, and running processes persist between commands
  2. Long-Running Commands:
    • Commands never get killed automatically
    • Set timeout to control how long to wait for output
    • For daemons/servers, append ’&’ to run in background
    • Use empty command "" to check progress
  3. Multiple Terminals: Use different terminal_id values to run multiple concurrent sessions
  4. Interactive Processes:
    • Special keys (C-c, C-d, etc.) work automatically when a process is running
    • Use is_input=true for regular text input to running processes
    • Use no_enter=true for Vim navigation, password typing, or multi-step commands
  5. Output Handling: Large outputs are automatically truncated. The tool provides the most relevant parts of the output for analysis.

​
Special Keys Reference

Common tmux key names:
  • BSpace (not Backspace)
  • DC (not Delete)
  • IC (not Insert)
  • Escape (not Esc)
  • Enter (not Return)
  • Space (not Spacebar)

Build docs developers (and LLMs) love

Get started for freeTalk to us