​
Overview

The vibekit local exec command runs shell commands inside a sandbox environment. It supports real-time streaming, background execution, and output capture.

​
Syntax

vibekit local exec [options]

​
Options

OptionAliasDescriptionDefault
--env <name>-eEnvironment name or IDInteractive prompt
--command <cmd>-cCommand to executeInteractive prompt
--timeout <ms>-tTimeout in milliseconds30000 (30s)
--background-bRun in backgroundfalse
--streamEnable streaming outputfalse
--save-output <file>Save output to fileNone

​
Examples

​
Basic Command Execution

Run a simple command: 
vibekit local exec -e my-env -c "ls -la"
Interactive mode (prompts for environment and command): 
vibekit local exec

​
Package Management

Install dependencies: 
# npm
vibekit local exec -e my-env -c "npm install"

# yarn
vibekit local exec -e my-env -c "yarn install"

# pip
vibekit local exec -e my-env -c "pip install -r requirements.txt"
With streaming for long operations: 
vibekit local exec -e my-env -c "npm install" --stream

​
Running Tests

Execute test suites: 
# JavaScript/Node.js
vibekit local exec -e my-env -c "npm test" --timeout 300000

# Python
vibekit local exec -e my-env -c "pytest" --stream

# Go
vibekit local exec -e my-env -c "go test ./..." --save-output test-results.json

​
Development Servers

Start development servers: 
# Start in background
vibekit local exec -e my-env -c "npm run dev" --background

# With streaming logs
vibekit local exec -e my-env -c "npm start" --stream

# With custom timeout for long-running
vibekit local exec -e my-env -c "python manage.py runserver" --timeout 0

​
Build Processes

Run build commands: 
# Frontend build
vibekit local exec -e my-env -c "npm run build" --stream

# Docker build
vibekit local exec -e my-env -c "docker build -t myapp ." --timeout 600000

# Multi-step build
vibekit local exec -e my-env -c "npm run clean && npm run build && npm run package"

​
Command Execution

​
Shell Processing

Commands are executed using the default shell (/bin/sh). For shell-specific features: 
# Bash-specific
vibekit local exec -e my-env -c "bash -c 'source ~/.bashrc && npm start'"

# Using environment variables
vibekit local exec -e my-env -c "NODE_ENV=production npm run build"

# Pipes and redirects
vibekit local exec -e my-env -c "cat package.json | jq '.dependencies'"

​
Working Directory

Commands execute in the environment’s working directory (default: /vibe0): 
# Check working directory
vibekit local exec -e my-env -c "pwd"

# Change directory within command
vibekit local exec -e my-env -c "cd src && npm test"

​
Multiple Commands

Chain commands: 
# Using && (stops on error)
vibekit local exec -e my-env -c "npm install && npm test && npm build"

# Using ; (continues on error)
vibekit local exec -e my-env -c "npm test; npm run lint; npm audit"

# Using || (fallback)
vibekit local exec -e my-env -c "npm test || echo 'Tests failed'"

​
Output Handling

​
Standard Output

Default behavior shows output after completion: 
✅ Command completed (exit code: 0)

📤 STDOUT:
Hello from the sandbox!
Files listed successfully.

📤 STDERR:
npm WARN optional dependency...

​
Streaming Output

With --stream flag, output appears in real-time: 
vibekit local exec -e my-env -c "npm install" --stream
📤 npm install
📤 added 150 packages from 80 contributors
📤 found 0 vulnerabilities

​
Saving Output

Capture output to file: 
# Save all output
vibekit local exec -e my-env -c "npm audit" --save-output audit-report.json

# Output file format:
{
  "command": "npm audit",
  "exitCode": 0,
  "stdout": "...",
  "stderr": "...",
  "timestamp": "2024-01-15T10:30:00Z",
  "environment": "my-env"
}

​
Timeout Configuration

​
Setting Timeouts

# 60 seconds
vibekit local exec -e my-env -c "npm test" --timeout 60000

# 5 minutes
vibekit local exec -e my-env -c "npm run integration-tests" --timeout 300000

# No timeout (for servers)
vibekit local exec -e my-env -c "npm run dev" --timeout 0

​
Common Timeout Values

TaskRecommended Timeout
Quick commands30000 (30s) - default
Package install120000 (2m)
Test suites300000 (5m)
Builds600000 (10m)
Dev servers0 (no timeout)

​
Background Execution

Run commands without waiting: 
# Start server in background
vibekit local exec -e my-env -c "npm run server" --background

# Background with streaming (shows initial output)
vibekit local exec -e my-env -c "python app.py" --background --stream
Note: Background processes continue until the environment is stopped or deleted.

​
Error Handling

​
Exit Codes

The command preserves the exit code from the executed command: 
# Check exit code
vibekit local exec -e my-env -c "exit 42"
# Output: ✅ Command completed (exit code: 42)

# Use in scripts
if vibekit local exec -e my-env -c "npm test"; then
  echo "Tests passed"
else
  echo "Tests failed"
fi

​
Error Output

Errors are captured in stderr: 
vibekit local exec -e my-env -c "ls /nonexistent"
# Shows error in STDERR section

​
Advanced Usage

​
Environment Variables

Access environment variables: 
# Print all variables
vibekit local exec -e my-env -c "env"

# Use specific variable
vibekit local exec -e my-env -c 'echo "Running in $NODE_ENV mode"'

​
File Operations

Work with files: 
# Create file
vibekit local exec -e my-env -c "echo 'Hello' > test.txt"

# Read file
vibekit local exec -e my-env -c "cat test.txt"

# Process files
vibekit local exec -e my-env -c "find . -name '*.js' -exec eslint {} +"

​
Network Operations

Network commands: 
# Check connectivity
vibekit local exec -e my-env -c "curl -I https://api.example.com"

# Download files
vibekit local exec -e my-env -c "wget https://example.com/file.zip"

# API calls
vibekit local exec -e my-env -c "curl -X POST -d '{\"test\":true}' http://localhost:3000/api"

​
Scripting

​
Batch Operations

Execute in multiple environments: 
#!/bin/bash
for env in $(vibekit local list --json | jq -r '.[].name'); do
  echo "Running tests in $env"
  vibekit local exec -e "$env" -c "npm test" --save-output "test-$env.json"
done

​
Conditional Execution

# Run different commands based on environment
if vibekit local exec -e my-env -c "test -f package.json"; then
  vibekit local exec -e my-env -c "npm install"
elif vibekit local exec -e my-env -c "test -f requirements.txt"; then
  vibekit local exec -e my-env -c "pip install -r requirements.txt"
fi

​
Output Processing

# Extract version
version=$(vibekit local exec -e my-env -c "node --version" | grep -o 'v[0-9.]*')

# Parse JSON output
deps=$(vibekit local exec -e my-env -c "cat package.json" | jq '.dependencies | keys[]')

​
Performance Tips

  1. Use streaming for long-running commands to see progress
  2. Set appropriate timeouts to avoid hanging
  3. Run heavy tasks in background when possible
  4. Save output for large results instead of printing to terminal
  5. Batch similar commands to reduce overhead

​
Troubleshooting

​
Command Not Found

# Check if command exists
vibekit local exec -e my-env -c "which npm"

# Install missing tools
vibekit local exec -e my-env -c "apt-get update && apt-get install -y curl"

​
Permission Denied

# Make script executable
vibekit local exec -e my-env -c "chmod +x script.sh"

# Run with proper permissions
vibekit local exec -e my-env -c "sudo npm install -g typescript"

​
Timeout Issues

# Increase timeout for slow commands
vibekit local exec -e my-env -c "npm install" --timeout 300000

# Use no timeout for servers
vibekit local exec -e my-env -c "npm run dev" --timeout 0

​
Output Too Large

# Save to file instead
vibekit local exec -e my-env -c "npm list" --save-output deps.json

# Pipe to file within command
vibekit local exec -e my-env -c "find . -type f > files.txt"

​
Best Practices

  1. Quote complex commands to avoid shell interpretation issues
  2. Use streaming for commands with progressive output
  3. Save output for commands that produce lots of data
  4. Set realistic timeouts based on expected duration
  5. Check exit codes in automation scripts