Commands API

Execute commands on remote machines.

Execute Command


POST /commands

Request Body

Field	Type	Required	Description
`machine_id`	string	Yes	Target machine ID
`command`	string	Yes	Command to execute
`cwd`	string	No	Working directory
`env`	object	No	Environment variables
`timeout`	number	No	Timeout in milliseconds
`user`	string	No	Run as user

Example


curl -X POST https://api.cmdop.com/v1/commands \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_id": "mach_abc123",
    "command": "ls -la /var/log",
    "timeout": 30000
  }'

Response


{
  "data": {
    "id": "cmd_xyz789",
    "machine_id": "mach_abc123",
    "command": "ls -la /var/log",
    "stdout": "total 48\ndrwxr-xr-x  6 root root  4096 Jan 20 12:00 .\n...",
    "stderr": "",
    "exit_code": 0,
    "duration": 150,
    "started_at": "2024-01-20T15:45:00Z",
    "finished_at": "2024-01-20T15:45:00Z"
  }
}

Execute Async

For long-running commands:


POST /commands/async

Example


curl -X POST https://api.cmdop.com/v1/commands/async \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_id": "mach_abc123",
    "command": "npm run build"
  }'

Response


{
  "data": {
    "id": "cmd_xyz789",
    "status": "running"
  }
}

Get Command Status


GET /commands/:id

Response


{
  "data": {
    "id": "cmd_xyz789",
    "status": "completed",
    "exit_code": 0,
    "stdout": "Build successful",
    "stderr": "",
    "started_at": "2024-01-20T15:45:00Z",
    "finished_at": "2024-01-20T15:46:30Z"
  }
}

Cancel Command


DELETE /commands/:id

Sends SIGTERM to the running command.

Response


{
  "data": {
    "cancelled": true
  }
}

Batch Execute

Execute on multiple machines:


POST /commands/batch

Request Body


{
  "machine_ids": ["mach_1", "mach_2", "mach_3"],
  "command": "apt update"
}

Response


{
  "data": {
    "mach_1": {
      "exit_code": 0,
      "stdout": "..."
    },
    "mach_2": {
      "exit_code": 0,
      "stdout": "..."
    },
    "mach_3": {
      "exit_code": 1,
      "stderr": "Permission denied"
    }
  }
}

Command History


GET /machines/:id/commands

Query Parameters

Parameter	Type	Description
`since`	string	ISO timestamp
`limit`	number	Results per page
`offset`	number	Pagination offset

Response


{
  "data": [
    {
      "id": "cmd_xyz789",
      "command": "ls -la",
      "exit_code": 0,
      "duration": 150,
      "executed_at": "2024-01-20T15:45:00Z"
    }
  ],
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}