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.

Why This Tool Exists

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

  1. Use PowerShell Syntax: Always use proper PowerShell cmdlets
  2. Include ConvertTo-Json: For commands that return objects, pipe to ConvertTo-Json to avoid truncation
  3. Handle Dynamic Commands: Use input variables for commands that change between runs
  4. Specify Full Paths: Use absolute paths when working with files
  5. 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"

System Information

"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

Using Workflow Input 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'"

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'"

Integration with Other Tools

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

  1. Always use PowerShell syntax, not Unix/Bash commands
  2. Pipe object output to ConvertTo-Json to see full results
  3. Use absolute paths for file operations
  4. Consider using -Force parameters to avoid prompts
  5. Handle errors gracefully with -ErrorAction
  6. Test complex commands before including in workflows
  7. Use input variables for dynamic command components
  8. Remember commands are stateless between executions