Command API Reference

April 2, 2026 · View on GitHub

💡 Async Version: This documentation covers the synchronous API. For async/await support, see AsyncCommand which provides the same functionality with async methods.

Command Execution Guide - Learn how to execute commands in sessions

Overview

The Command module provides methods for executing shell commands within a session in the AgentBay cloud environment. Commands support configurable timeouts and optional working directory or environment settings.

Command

class Command(BaseService)

Sync command execution service for session shells in the AgentBay cloud environment.

Use this class for non-blocking command execution; for blocking/synchronous usage, refer to the Command service in the sync API.

execute_command

def execute_command(command: str,
                    timeout_ms: int = 50000,
                    cwd: Optional[str] = None,
                    envs: Optional[Dict[str, str]] = None) -> CommandResult

Execute a shell command with optional working directory and environment variables.

Executes a shell command in the session environment with configurable timeout, working directory, and environment variables. The command runs with session user permissions in a Linux shell environment.

Arguments:

command: The shell command to execute
timeout_ms: Timeout in milliseconds (default: 50000ms/50s).
cwd: The working directory for command execution. If not specified,

the command runs in the default session directory envs: Environment variables as a dictionary of key-value pairs. These variables are set for the command execution only

Returns:

CommandResult: Result object containing:

success: Whether the command executed successfully (exit_code == 0)
output: Command output for backward compatibility (stdout + stderr)
exit_code: The exit code of the command execution (0 for success)
stdout: Standard output from the command execution
stderr: Standard error from the command execution
trace_id: Trace ID for error tracking (only present when exit_code != 0)
request_id: Unique identifier for this API request
error_message: Error description if execution failed

Raises:

CommandError: If the command execution fails due to system errors

Example:

session = agent_bay.create().session result = session.command.execute_command("echo 'Hello, World!'") print(result.output) print(result.exit_code) session.delete()

Example:

result = session.command.execute_command( "pwd", timeout_ms=5000, cwd="/tmp", envs={"TEST_VAR": "test_value"} ) print(result.stdout) session.delete()

run

def run(command: str,
        timeout_ms: int = 50000,
        cwd: Optional[str] = None,
        envs: Optional[Dict[str, str]] = None) -> CommandResult

Alias of execute_command() for better ergonomics and LLM friendliness.

exec

def exec(command: str,
         timeout_ms: int = 50000,
         cwd: Optional[str] = None,
         envs: Optional[Dict[str, str]] = None) -> CommandResult

Alias of execute_command() for better ergonomics and LLM friendliness.

Best Practices

Always specify appropriate timeout values based on expected command duration
Handle command execution errors gracefully
Use absolute paths when referencing files in commands
Be aware that commands run with session user permissions
Clean up temporary files created by commands