Execute Terminal Command - Cyberdesk Docs

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.

Session Behavior

Persistent by default: execute_terminal_command reuses the same PowerShell session by default within a workflow run.

Variables, the current directory, and other shell state can carry over between consecutive terminal commands

Timeout Behavior

By default, execute_terminal_command waits up to 30 seconds for a command to complete. For long-running operations, you can specify a custom timeout using the duration parameter.

Cyberdriver 1.0.2+: If a one-shot PowerShell command reaches its timeout, Cyberdriver returns control to Cyberdesk but lets the command keep running in the background. To avoid runaway resource usage, Cyberdriver allows up to 10 timed-out background PowerShell commands at once; additional timed-out commands are terminated until a background slot is released.

Using Duration Parameter

"Use execute_terminal_command with duration=180 (3 minutes) to run the data 
processing script: 'python C:\Scripts\process_large_file.py' and allow it to 
complete. The workflow will wait up to 3 minutes before continuing."

Background Execution

On Cyberdriver 1.0.2+, when a one-shot command exceeds its timeout and a background slot is available, it continues running in the background while the workflow proceeds. This is useful for:

Fire-and-forget operations
Long-running background tasks
Commands that write output to files

Example:

"Use execute_terminal_command with duration=5 to start the backup process: 
'Start-Process powershell -ArgumentList "-File C:\Scripts\backup.ps1" 
-RedirectStandardOutput C:\Logs\backup.log'. The command will start the backup 
in background and continue immediately."

Best Practices for Long Commands

Redirect output to files - Use > output.txt or -RedirectStandardOutput
Don’t rely on command output - If timeout is reached, stdout/stderr will be empty
Verify completion separately - Use subsequent commands or focused_action to check results
Use appropriate timeouts - Match duration to expected command runtime

Example with file output:

"Use execute_terminal_command with duration=10 to start data export:
'python export_script.py > C:\Output\export_log.txt 2>&1'
Then use execute_terminal_command to check progress:
'Get-Content C:\Output\export_log.txt -Tail 20 | ConvertTo-Json'"

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
Use a Workflow Allowlist For Sensitive Flows: If a workflow only needs a small set of terminal commands, configure the workflow’s terminal command allowlist so the agent can only run those approved command templates

Prompt Template

"Use execute_terminal_command to run '[PowerShell command]' to [purpose of command]"

Workflow Terminal Allowlist

Cyberdesk workflows can optionally define a terminal command allowlist in the workflow editor. When present:

The allowlist is enforced server-side before a command is sent to Cyberdriver.
The agent may only run commands that match one of the approved command templates, or the resolved command produced from that template for the current run.
Allowlist templates may include input values like {value}, sensitive values like {$value}, runtime values like {{value}}, and loop-item runtime values like {{loop_item}}.
working_directory is not allowed with an active allowlist. Prefer explicit paths inside the approved command itself.
Dynamic input or runtime variables are still fine as long as the resulting command matches an approved template.

Recommended pattern: list one approved PowerShell command per line in the workflow editor, then prompt the agent to use only those approved commands for terminal work.

Using Persistent Shell State

"Use execute_terminal_command to run '$env:REPORT_DIR = \"C:\Reports\"'. Later in the workflow, use execute_terminal_command again to run 'Get-ChildItem $env:REPORT_DIR | ConvertTo-Json'"

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

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
Reuse the default persistent session when follow-up commands depend on earlier shell state

​What is Execute Terminal Command?

​Why This Tool Exists

​Session Behavior

​Timeout Behavior

​Using Duration Parameter

​Background Execution

​Best Practices for Long Commands

​PowerShell Syntax Guide

​❌ Unix/Bash Commands (DON’T USE)

​✅ PowerShell Equivalents (USE THESE)

​How to Prompt for Terminal Commands

​Best Practices

​Prompt Template

​Workflow Terminal Allowlist

​Using Persistent Shell State

​Real-World Examples

​File Operations

​API Integration

​Data Processing

​System Information

​Common PowerShell Commands

​File and Directory Operations

​Text Processing

​Web Requests

​Dynamic Commands with Variables

​Using Workflow Input Variables

​Using Runtime Variables

​Building Dynamic Commands

​Conditional Command Execution

​Sensitive Variables in Terminal Commands

​Best Practices

​Example

​Advanced Patterns

​Batch Processing

​System Monitoring

​Log Analysis

​Integration with Other Tools

​With File Export

​With Focused Action

​Creating Reports

​Error Handling

​Checking Command Success

​Graceful Failures

​Best Practices Summary

What is Execute Terminal Command?

Why This Tool Exists

Session Behavior

Timeout Behavior

Using Duration Parameter

Background Execution

Best Practices for Long Commands

PowerShell Syntax Guide

❌ Unix/Bash Commands (DON’T USE)

✅ PowerShell Equivalents (USE THESE)

How to Prompt for Terminal Commands

Best Practices

Prompt Template

Workflow Terminal Allowlist

Using Persistent Shell State

Real-World Examples

File Operations

API Integration

Data Processing

System Information

Common PowerShell Commands

File and Directory Operations

Text Processing

Web Requests

Dynamic Commands with Variables

Using Workflow Input Variables

Using Runtime Variables

Building Dynamic Commands

Conditional Command Execution

Sensitive Variables in Terminal Commands

Best Practices

Example

Advanced Patterns

Batch Processing

System Monitoring

Log Analysis

Integration with Other Tools

With File Export

With Focused Action

Creating Reports

Error Handling

Checking Command Success

Graceful Failures

Best Practices Summary