Execute a shell command

POST 
/command/shell

Execute a command through /bin/sh -c. Supports shell features like pipes, redirects, and variable expansion.

Request

Query Parameters

target_hostname string

Default value: _any

Target: _any (load-balanced), _all (broadcast), hostname (direct), or key:value (label group, e.g., group:web.dev).

application/json

Body

required

The shell command to execute.

command stringrequired

The full shell command string.

cwd string

Working directory for the command.

timeout integer

Possible values: >= 1 and <= 300

Default value: 30

Timeout in seconds (default 30, max 300).

Responses

202

Shell command execution accepted.

application/json

Schema

Schema

job_id uuid

The job ID used to process this request.

results

object[]

required

Array [

hostname stringrequired

The hostname of the agent that executed the command.

stdout string

Standard output of the command.

stderr string

Standard error output of the command.

exit_code integer

Exit code of the command.

duration_ms int64

Execution time in milliseconds.

changed boolean

Whether the command modified system state.

error string

Error message if the agent failed to process the request.

]

Example (from schema)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "hostname": "string",
      "stdout": "string",
      "stderr": "string",
      "exit_code": 0,
      "duration_ms": 0,
      "changed": true,
      "error": "string"
    }
  ]
}

400

Invalid request payload.

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

401

Unauthorized - API key required

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

403

Forbidden - Insufficient permissions

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

500

Error executing shell command.

application/json

Schema

Schema

error string

A description of the error that occurred.

details string

Additional details about the error.

code integer

The error code.

Example (from schema)

{
  "error": "Failed to retrieve status.",
  "details": "Failed due to network timeout.",
  "code": 500
}

Loading...