What is Execute Terminal Command?
Execute Terminal Command is a specialized tool that allows your agent to run PowerShell commands on the Windows machine during workflow execution. This enables system-level operations, file manipulations, and integrations that go beyond GUI interactions.
In your prompts, always refer to this tool as execute_terminal_command
(lowercase, with underscores).
PowerShell Only: This tool executes PowerShell commands on Windows. Do NOT use Unix/Bash syntax. Always use proper PowerShell cmdlets and syntax.
Many enterprise workflows require system-level operations:
- File system operations (copy, move, delete, rename)
- System administration tasks
- API calls and web requests
- Data processing and transformation
- Integration with command-line tools
- Batch operations on multiple files
The execute_terminal_command
tool ensures these operations are performed consistently, even during cached workflow runs.
Current Limitations
Stateless Execution: Currently, each command runs in a fresh PowerShell session. Commands do not share state or variables between executions.Want stateful PowerShell sessions? Contact the founders at founders@cyberdesk.io to have this feature prioritized!
PowerShell Syntax Guide
❌ Unix/Bash Commands (DON’T USE)
curl http://api.example.com
cat file.txt
ls -la
grep "pattern" file.txt
✅ PowerShell Equivalents (USE THESE)
Invoke-RestMethod -Uri "http://api.example.com"
Get-Content file.txt
Get-ChildItem -Force
Select-String -Pattern "pattern" -Path file.txt
How to Prompt for Terminal Commands
Best Practices
- Use PowerShell Syntax: Always use proper PowerShell cmdlets
- Include ConvertTo-Json: For commands that return objects, pipe to
ConvertTo-Json
to avoid truncation
- Handle Dynamic Commands: Use input variables for commands that change between runs
- Specify Full Paths: Use absolute paths when working with files
- Error Handling: Consider what should happen if a command fails
Prompt Template
"Use execute_terminal_command to run '[PowerShell command]' to [purpose of command]"
Real-World Examples
File Operations
"After downloading the reports, use execute_terminal_command to run
'Move-Item -Path C:\Downloads\*.pdf -Destination D:\Reports\{year}\{month}\ -Force'
to organize them by date"
API Integration
"Use execute_terminal_command to run this command:
'Invoke-RestMethod -Uri "https://api.company.com/webhook" -Method POST -Body (@{
order_id = "{order_id}"
status = "completed"
timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
} | ConvertTo-Json) -ContentType "application/json" | ConvertTo-Json -Depth 10'
to notify the system of order completion"
Data Processing
"Extract customer emails from the CSV file using execute_terminal_command:
'Import-Csv C:\Data\customers.csv | Select-Object -ExpandProperty Email |
Out-File C:\Data\email_list.txt'
Then use mark_file_for_export on C:\Data\email_list.txt"
"Before starting the process, use execute_terminal_command to run
'Get-Process | Where-Object {$_.ProcessName -eq "TargetApp"} | ConvertTo-Json'
to check if the application is already running"
Common PowerShell Commands
File and Directory Operations
# List files
Get-ChildItem -Path "C:\Data" -Filter "*.pdf" | ConvertTo-Json
# Copy files
Copy-Item -Path "C:\Source\*" -Destination "D:\Backup\" -Recurse
# Create directory
New-Item -ItemType Directory -Path "C:\Reports\{date}" -Force
# Delete old files
Get-ChildItem -Path "C:\Temp" -Filter "*.tmp" |
Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)} |
Remove-Item -Force
Text Processing
# Search in files
Select-String -Path "C:\Logs\*.log" -Pattern "ERROR" | ConvertTo-Json
# Replace text in file
(Get-Content "C:\Config\settings.ini") -replace 'old_value', '{new_value}' |
Set-Content "C:\Config\settings.ini"
# Merge multiple files
Get-Content C:\Data\file1.txt, C:\Data\file2.txt |
Out-File C:\Data\merged.txt
Web Requests
# GET request
Invoke-RestMethod -Uri "https://api.example.com/data/{id}" | ConvertTo-Json -Depth 10
# POST with JSON body
$body = @{
name = "{customer_name}"
email = "{customer_email}"
} | ConvertTo-Json
Invoke-RestMethod -Uri "https://api.example.com/customers" -Method POST -Body $body -ContentType "application/json" | ConvertTo-Json
Dynamic Commands with Variables
"Use execute_terminal_command to run the entire command provided in the input
variable {powershell_command}. This allows different commands for each run."
Using Runtime Variables
"First, use focused_action to find the process ID of the hung application and
save it as {{process_id}}. Then use execute_terminal_command to run
'Stop-Process -Id {{process_id}} -Force' to terminate that specific process."
Building Dynamic Commands
"Construct and execute a PowerShell command to rename the file:
execute_terminal_command: 'Rename-Item -Path "C:\Output\report.pdf" -NewName "{client_name}_{report_date}.pdf"'
The {client_name} and {report_date} will be replaced with actual values."
Conditional Command Execution
"First check if the backup folder exists using execute_terminal_command:
'Test-Path D:\Backups\{date}'
If it returns False, create it using execute_terminal_command:
'New-Item -ItemType Directory -Path D:\Backups\{date} -Force'"
Sensitive Variables in Terminal Commands
Use {$variable}
for secrets required by terminal actions (e.g., tokens). Secrets are never logged or sent to LLMs and are resolved only at execution time. Avoid echoing them in command output or saving them to files.
Best Practices
- Do not print secrets (avoid
Write-Host
of secret values)
- Prefer passing secrets to commands that do not echo them to stdout
- Never persist secrets to disk or logs
- If a command would reveal the secret in output, capture only status and verify success via UI with
focused_action
Example
"Authenticate using a token {$api_token} via execute_terminal_command without printing it. Verify success on screen with focused_action instead of echoing the token."
Advanced Patterns
Batch Processing
"Process all CSV files in the input directory. Use execute_terminal_command:
'Get-ChildItem -Path C:\Input -Filter *.csv | ForEach-Object {
$data = Import-Csv $_.FullName
$data | Where-Object {$_.Status -eq "Active"} |
Export-Csv -Path ("C:\Output\" + $_.BaseName + "_filtered.csv") -NoTypeInformation
}'"
System Monitoring
"Check system resources before starting intensive process using execute_terminal_command:
'@{
CPU = (Get-Counter "\Processor(_Total)\% Processor Time" -SampleInterval 1 -MaxSamples 1).CounterSamples.CookedValue
Memory = (Get-Counter "\Memory\Available MBytes").CounterSamples.CookedValue
Disk = (Get-PSDrive C | Select-Object -ExpandProperty Free) / 1GB
} | ConvertTo-Json'"
Log Analysis
"Extract error counts from today's logs using execute_terminal_command:
'Get-Content C:\Logs\app_{date}.log |
Select-String -Pattern "ERROR|CRITICAL" |
Group-Object -Property Line |
Select-Object Count, Name |
ConvertTo-Json'"
With File Export
"Use execute_terminal_command to create a ZIP archive:
'Compress-Archive -Path C:\Reports\*.pdf -DestinationPath C:\Archive\reports_{date}.zip'
Then use mark_file_for_export on C:\Archive\reports_{date}.zip"
With Focused Action
"Use focused_action to read the order number from the screen.
Then use execute_terminal_command to update the database:
'Invoke-SqlCmd -Query "UPDATE Orders SET Status = ''Processed'' WHERE OrderID = ''{order_number}''" -ServerInstance "localhost\SQLEXPRESS"'"
Creating Reports
"Gather system information using multiple execute_terminal_command calls:
1. 'Get-ComputerInfo | Select-Object CsName, OsName, OsVersion | ConvertTo-Json'
2. 'Get-Service | Where-Object {$_.Status -eq "Running"} | Select-Object Name, DisplayName | ConvertTo-Json'
3. 'Get-EventLog -LogName Application -Newest 10 | Select-Object TimeGenerated, Message | ConvertTo-Json'
Compile results into a system report."
Error Handling
Checking Command Success
"Try to stop the service using execute_terminal_command:
'Stop-Service -Name "ServiceName" -Force -PassThru | ConvertTo-Json'
If the command fails or returns an error, use focused_action to check
for error messages and try alternative methods."
Graceful Failures
"Attempt to delete temporary files using execute_terminal_command:
'Remove-Item -Path C:\Temp\* -Force -ErrorAction SilentlyContinue'
The -ErrorAction SilentlyContinue ensures the workflow continues even if some files cannot be deleted."
Best Practices Summary
- Always use PowerShell syntax, not Unix/Bash commands
- Pipe object output to
ConvertTo-Json
to see full results
- Use absolute paths for file operations
- Consider using
-Force
parameters to avoid prompts
- Handle errors gracefully with
-ErrorAction
- Test complex commands before including in workflows
- Use input variables for dynamic command components
- Remember commands are stateless between executions