Commands API

TL;DR

The Commands API executes shell commands on remote machines via CMDOP. Send synchronous or async commands to specific machines by ID, retrieve output (stdout/stderr) and exit codes, cancel running commands, and batch-execute across multiple machines simultaneously. Supports custom working directories, environment variables, timeouts, and run-as-user options.

How do I execute a command?


POST /commands

What fields does the request body accept?

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


# Execute a command on a remote machine with a 30-second timeout
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"
  }
}

How do I execute a long-running command asynchronously?

For long-running commands:


POST /commands/async

Example


# Submit a long-running command; returns immediately with a command ID
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"
  }
}

How do I check command status and results?


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"
  }
}

How do I cancel a running command?


DELETE /commands/:id

Sends SIGTERM to the running command.

Response


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

How do I execute commands on multiple machines at once?

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"
    }
  }
}

How do I view command history for a machine?


GET /machines/:id/commands

What query parameters are supported?

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
  }
}