Terminal Commands - Utari Docs

Overview

The terminal commands capability gives your Utari workers the power to execute shell commands, install packages, run scripts, and interact with the command line interface in your workspace. This powerful tool enables workers to perform technical tasks like setting up environments, running builds, executing scripts, and managing processes.

Terminal Command Capabilities

Your workers can execute four types of terminal operations:

Execute Command

Run shell commands in blocking or non-blocking mode with full control over execution

Check Command Output

Monitor the progress and output of non-blocking commands running in background sessions

List Commands

View all running tmux sessions and their current status

Terminate Command

Stop running commands by killing their tmux sessions

Terminal commands execute in your workspace directory and have access to standard shell utilities, package managers, and installed tools.

Execute Command

The core capability for running shell commands with two execution modes:

Blocking Mode (Synchronous)

When to Use:

Quick commands that complete in seconds
Package installations
File operations (copy, move, delete)
Build processes
Script execution that completes quickly
Any command where you need immediate results

How It Works:

blocking=true
- Command runs synchronously
- Waits for completion
- Returns full output directly
- Automatically cleans up session
- NO need to call check_command_output

Example Commands:

npm install express
pip install pandas --break-system-packages
apt-get update && apt-get install -y curl

Non-Blocking Mode (Asynchronous)

When to Use:

Long-running processes
Development servers
Watch processes
Background jobs
Continuous monitoring tasks
Any command that runs indefinitely

How It Works:

blocking=false (default)
- Command runs in background tmux session
- Returns immediately
- Use check_command_output to monitor
- Session persists until terminated
- Must manually check output

Example Commands:

npm run dev
python -m http.server 8000
node server.js

Command Execution Examples

Installing Dependencies

Node.js/NPM
Python/Pip
System Packages

    # Install single package (blocking)
    npm install express
    
    # Install dev dependencies (blocking)
    npm install --save-dev jest
    
    # Install from package.json (blocking)
    npm install
    
    # Global installation (blocking)
    npm install -g typescript

    # Install package (blocking)
    # ALWAYS use --break-system-packages flag
    pip install pandas --break-system-packages
    
    # Install from requirements (blocking)
    pip install -r requirements.txt --break-system-packages
    
    # Install specific version (blocking)
    pip install requests==2.28.0 --break-system-packages
    
    # Upgrade package (blocking)
    pip install --upgrade numpy --break-system-packages

    # Update package list (blocking)
    apt-get update
    
    # Install package (blocking)
    apt-get install -y curl
    
    # Install multiple packages (blocking)
    apt-get install -y git wget vim

Python Package Installation: Always use the --break-system-packages flag when installing Python packages with pip to avoid system package conflicts.

Running Scripts

# Run script (blocking for quick scripts)
node script.js

# Run with arguments (blocking)
node process.js --input data.json --output results.json

# Start development server (non-blocking)
npm run dev

# Run build (blocking)
npm run build

File and Directory Operations

# Create directory (blocking)
mkdir -p /workspace/project/src

# Create multiple directories (blocking)
mkdir -p logs temp data

# Create file (blocking)
touch README.md

# Create with content (blocking)
echo "# Project Title" > README.md

Check Command Output

Monitor non-blocking commands running in background sessions.

Execute Non-Blocking Command

Start a command in non-blocking mode (blocking=false).

Get Session Information

Note the tmux session ID returned when the command starts.

Check Output

Use check_command_output with the session ID to view progress and output.

Monitor Periodically

Call check_command_output multiple times to track ongoing progress.

IMPORTANT: Only use check_command_output for commands executed with blocking=false.Blocking commands return output directly and automatically clean up their sessions—calling check_command_output on them will fail.

Example Workflow

1. Start server (non-blocking):
   execute_command("npm run dev", blocking=false)
   → Returns: session_id = "tmux-session-123"

2. Check if server started:
   check_command_output(session_id="tmux-session-123")
   → Returns: Output showing "Server running on port 3000"

3. Continue monitoring:
   check_command_output(session_id="tmux-session-123")
   → Returns: Latest logs and status

List Commands

View all active tmux sessions to see what’s currently running. Use Cases:

Check which background processes are active
Identify session IDs for monitoring
Verify servers are still running
Audit workspace processes
Troubleshoot command execution

Example Output:

Active tmux sessions:
- session-abc123: npm run dev (running)
- session-def456: python server.py (running)
- session-ghi789: bash watch.sh (running)

Terminate Command

Stop running commands by killing their tmux sessions.

Identify Session

Use list_commands to find the session ID of the command you want to stop.

Terminate Session

Call terminate_command with the session ID.

Verify Termination

Optionally use list_commands again to confirm the session is stopped.

Common Scenarios:

List running commands
Find dev server session ID
Terminate the session
Server stops immediately

Terminating a session immediately kills the process. Ensure you don’t need the output or that important work is saved before terminating.

Choosing Execution Mode

Use Blocking Mode (blocking=true) For:

Quick Operations

Commands that complete in seconds or minutes

Package Installation

npm install, pip install, apt-get install

File Operations

Copy, move, delete, create files and folders

Build Processes

npm run build, make, compilation tasks

Script Execution

Short scripts that complete and exit

System Commands

Configuration, setup, one-time operations

Use Non-Blocking Mode (blocking=false) For:

Servers

Development servers, web servers, API servers

Watch Processes

File watchers, auto-recompiling tools

Long-Running Jobs

Data processing, large file operations

Monitoring

Continuous monitoring scripts

Background Tasks

Tasks that should run while you do other work

Interactive Programs

Programs that require ongoing interaction

Common Workflows

Setting Up a Development Environment

Update System

    apt-get update (blocking)

Install Dependencies

    apt-get install -y nodejs npm python3-pip (blocking)

Install Project Packages

    npm install (blocking)
    pip install -r requirements.txt --break-system-packages (blocking)

Start Development Server

    npm run dev (non-blocking)

Verify Server

    check_command_output (monitor server startup)

Running Tests and Builds

Install Test Dependencies

    npm install --save-dev jest (blocking)

Run Tests

    npm test (blocking)

Build Project

    npm run build (blocking)

Verify Build Output

    ls -la dist/ (blocking)

Managing Long-Running Processes

Start Background Process

    python data_processor.py (non-blocking)

Save the session ID returned

Monitor Progress

    check_command_output(session_id)

Repeat periodically to track progress

List All Processes

    list_commands

View all active sessions

Terminate When Complete

    terminate_command(session_id)

Or let it complete naturally

Best Practices

Choose Right Mode

Use blocking for quick tasks, non-blocking for long-running processes

Monitor Non-Blocking

Always check output of non-blocking commands to verify they’re running correctly

Clean Up Sessions

Terminate completed non-blocking commands to free resources

Handle Errors

Check command exit codes and output for errors

Use Full Paths

Specify complete file paths to avoid ambiguity

Test Commands First

Test complex commands manually before automating

Include Flags

Always use required flags (like —break-system-packages for pip)

Document Sessions

Keep track of what each non-blocking session is doing

Troubleshooting

Command fails with permission error

Try:

Using sudo if appropriate (apt-get, system operations)
Checking file/directory permissions with ls -la
Ensuring you’re in the correct directory
Verifying the command syntax is correct

Package installation fails

For pip:

Always include --break-system-packages flag
Try updating pip: pip install --upgrade pip --break-system-packages
Check internet connectivity

For npm:

Clear cache: npm cache clean --force
Delete node_modules and reinstall
Check package.json for syntax errors

Can't check output of blocking command

Remember:

Blocking commands return output directly
They automatically clean up sessions
Don’t use check_command_output for them
The output is in the execute_command response

Non-blocking command not running

Verify:

Use list_commands to see active sessions
Check output with check_command_output
Look for errors in the command syntax
Ensure required dependencies are installed
Try running in blocking mode first to debug

Session appears stuck

Solutions:

Check output to see if it’s waiting for input
Verify the command is appropriate for non-blocking
Terminate and restart if necessary
Check for errors in the command output

Command works locally but fails in Utari

Check:

Environment differences (paths, installed packages)
Missing dependencies
Different shell or system configuration
Required system packages not installed

Security Considerations

Security Best Practices:

Never expose sensitive credentials in commands
Use environment variables for secrets
Be cautious with rm -rf commands
Validate user input before executing
Limit permissions where possible
Avoid running untrusted scripts
Monitor command execution for unusual activity

Advanced Usage

Chaining Commands

# Run second only if first succeeds
npm install && npm run build

# Multi-step setup
apt-get update && apt-get install -y curl && curl --version

Environment Variables

# Set for single command
NODE_ENV=production npm start

# Export for session
export API_KEY=abc123 && node server.js

# Use in script
DATABASE_URL=postgres://localhost/db python migrate.py

Working with Files

# Display contents
cat file.txt

# Page through large files
less large_file.log

# Show first/last lines
head -n 20 file.txt
tail -n 50 file.txt

# Follow growing file
tail -f app.log

Summary

You’ve successfully learned:

How to execute commands in blocking vs non-blocking mode

When to use each execution mode for optimal performance

How to monitor non-blocking commands with check_command_output

How to list and terminate running command sessions

Best practices for package installation and script execution

Common workflows for development environment setup

Troubleshooting techniques for command execution issues

Terminal commands give your Utari workers powerful capabilities to set up environments, run scripts, manage processes, and perform technical operations—all through natural language instructions.

Next Steps

Files and Folder Tool

Manage files created or modified by terminal commands

Worker Configuration

Set up workers optimized for technical tasks

Triggers

Automate terminal commands on a schedule

Integrations

Combine terminal commands with third-party apps

Getting started

Getting Started With Workers

Worker Tools

Worker Integrations

Worker Knowledge

Worker Triggers

​Overview

​Terminal Command Capabilities

Execute Command

Check Command Output

List Commands

Terminate Command

​Execute Command

​Blocking Mode (Synchronous)

​Non-Blocking Mode (Asynchronous)

​Command Execution Examples

​Installing Dependencies

​Running Scripts

​File and Directory Operations

​Check Command Output

​Example Workflow

​List Commands

​Terminate Command

​Choosing Execution Mode

​Use Blocking Mode (blocking=true) For:

Quick Operations

Package Installation

File Operations

Build Processes

Script Execution

System Commands

​Use Non-Blocking Mode (blocking=false) For:

Servers

Watch Processes

Long-Running Jobs

Monitoring

Background Tasks

Interactive Programs

​Common Workflows

​Setting Up a Development Environment

​Running Tests and Builds

​Managing Long-Running Processes

​Best Practices

Choose Right Mode

Monitor Non-Blocking

Clean Up Sessions

Handle Errors

Use Full Paths

Test Commands First

Include Flags

Document Sessions

​Troubleshooting

​Security Considerations

​Advanced Usage

​Chaining Commands

​Environment Variables

​Working with Files

​Summary

​Next Steps

Files and Folder Tool

Worker Configuration

Triggers

Integrations

Overview

Terminal Command Capabilities

Execute Command

Blocking Mode (Synchronous)

Non-Blocking Mode (Asynchronous)

Command Execution Examples

Installing Dependencies

Running Scripts

File and Directory Operations

Check Command Output

Example Workflow

List Commands

Terminate Command

Choosing Execution Mode

Use Blocking Mode (blocking=true) For:

Use Non-Blocking Mode (blocking=false) For:

Common Workflows

Setting Up a Development Environment

Running Tests and Builds

Managing Long-Running Processes

Best Practices

Troubleshooting

Security Considerations

Advanced Usage

Chaining Commands

Environment Variables

Working with Files

Summary

Next Steps