Commands API

Execute commands on remote machines.

Execute Command


const result = await client.commands.exec(
  'machine-id',
  'ls -la'
);

Response


interface CommandResult {
  stdout: string;
  stderr: string;
  exitCode: number;
  duration: number; // milliseconds
}

Options


const result = await client.commands.exec(
  'machine-id',
  'npm install',
  {
    cwd: '/app',
    env: { NODE_ENV: 'production' },
    timeout: 60000, // 60 seconds
    user: 'deploy',
  }
);

Available Options

Option	Type	Description
`cwd`	string	Working directory
`env`	object	Environment variables
`timeout`	number	Timeout in milliseconds
`user`	string	Run as user
`shell`	string	Shell to use

Streaming Output

For long-running commands:


const stream = client.commands.stream(
  'machine-id',
  'npm run build'
);
 
stream.on('stdout', (data) => {
  process.stdout.write(data);
});
 
stream.on('stderr', (data) => {
  process.stderr.write(data);
});
 
stream.on('exit', (code) => {
  console.log('Exit code:', code);
});
 
// Send input
stream.write('yes\n');
 
// Kill the command
stream.kill();

Async Execution

Run commands without waiting:


const { commandId } = await client.commands.execAsync(
  'machine-id',
  'npm run long-task'
);
 
// Check status later
const status = await client.commands.status(commandId);
console.log(status.state); // 'running' | 'completed' | 'failed'
 
// Get result when complete
const result = await client.commands.result(commandId);

Batch Execution

Run on multiple machines:


const results = await client.commands.execBatch(
  ['machine-1', 'machine-2', 'machine-3'],
  'apt update && apt upgrade -y'
);
 
for (const [machineId, result] of Object.entries(results)) {
  console.log(`${machineId}: exit code ${result.exitCode}`);
}

Script Execution

Run multi-line scripts:


const script = `
#!/bin/bash
set -e
cd /app
git pull
npm install
npm run build
pm2 restart all
`;
 
const result = await client.commands.script(
  'machine-id',
  script
);

Command History


const history = await client.commands.history('machine-id', {
  limit: 50,
  since: new Date('2024-01-01'),
});
 
for (const cmd of history) {
  console.log(cmd.command, cmd.exitCode, cmd.timestamp);
}

Abort Command


const stream = client.commands.stream(
  'machine-id',
  'npm run long-task'
);
 
// Abort after 30 seconds
setTimeout(() => {
  stream.kill('SIGTERM');
}, 30000);