⚡ Command API Reference

March 2, 2026 · View on GitHub

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.

📚 Tutorial

Command Execution Guide

Learn how to execute commands in sessions

Command

Async 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.

Constructor

public Command(Session session)

Methods

execute

public CommandResult execute(String command)

public CommandResult execute(String command, String input)

Execute a shell command with default timeout (50000ms). Note: The input parameter is currently not used in the implementation.

Parameters:

  • command (String): The shell command to execute
  • input (String): Input parameter (currently unused)

Returns:

  • CommandResult: CommandResult Result object containing execution details

executeCommand

public CommandResult executeCommand(String command, int timeoutMs)

public CommandResult executeCommand(String command, int timeoutMs, String cwd, Map<String, String> envs)

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.

Parameters:

  • command (String): The shell command to execute
  • timeoutMs (int): Timeout in milliseconds (default: 50000ms/50s).
  • cwd (String): The working directory for command execution. If not specified, the command runs in the default session directory
  • envs (Map<String,String>): Environment variables as a map of key-value pairs. These variables are set for the command execution only

Returns:

  • CommandResult: CommandResult Result object containing:
    • success: Whether the command executed successfully (exit_code == 0)
    • output: Command output for backward compatibility (stdout + stderr)
    • exitCode: The exit code of the command execution (0 for success)
    • stdout: Standard output from the command execution
    • stderr: Standard error from the command execution
    • traceId: Trace ID for error tracking (only present when exit_code != 0)
    • requestId: Unique identifier for this API request
    • errorMessage: Error description if execution failed

Throws:

  • IllegalArgumentException: If environment variables contain non-string keys or values

run

public CommandResult run(String command, int timeoutMs)

public CommandResult run(String command, int timeoutMs, String cwd, Map<String, String> envs)

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

Parameters:

  • command (String): The shell command to execute
  • timeoutMs (int): Timeout in milliseconds
  • cwd (String): The working directory for command execution
  • envs (Map<String,String>): Environment variables as a map of key-value pairs

Returns:

  • CommandResult: CommandResult Result object containing execution details

exec

public CommandResult exec(String command, int timeoutMs)

public CommandResult exec(String command, int timeoutMs, String cwd, Map<String, String> envs)

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

Parameters:

  • command (String): The shell command to execute
  • timeoutMs (int): Timeout in milliseconds
  • cwd (String): The working directory for command execution
  • envs (Map<String,String>): Environment variables as a map of key-value pairs

Returns:

  • CommandResult: CommandResult Result object containing execution details

💡 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