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

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

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