Download

TL;DR

The download service fetches files from URLs and saves them to remote machines. Use downloadFile() for full-featured downloads with progress tracking, chunked transfer, custom headers, and cancellation support. Use downloadUrl() for simple downloads without progress events. Progress callbacks report percent complete, bytes transferred, total size, and speed in bytes per second.

Download files from URLs to remote machines with progress tracking and chunked transfer.

How do I download a file?


import { CMDOPClient } from '@cmdop/node';
 
// Connect to the cloud relay
const client = await CMDOPClient.remote({ apiKey: 'cmdop_xxx' });
 
// Download a file from a URL to a path on the remote machine
const result = await client.download.downloadFile({
  machine: 'my-server',
  url: 'https://example.com/release.tar.gz',
  destination: '/tmp/release.tar.gz',
});
 
console.log(result.path);    // Destination path on the remote machine
console.log(result.size);    // Total bytes downloaded

How do I do a simple download without progress?


// downloadUrl() is a simpler variant that returns a plain promise (no progress)
const result = await client.download.downloadUrl({
  machine: 'my-server',
  url: 'https://example.com/config.json',
  destination: '/etc/app/config.json',
});

How do I track download progress?


// Start a download (returns immediately -- does not block until complete)
const download = client.download.downloadFile({
  machine: 'my-server',
  url: 'https://example.com/large-file.bin',
  destination: '/tmp/large-file.bin',
});
 
// Attach a progress callback to monitor download status
download.onProgress((progress) => {
  console.log(`${progress.percent}%`);                       // 0-100 percent complete
  console.log(`${progress.transferred} / ${progress.total} bytes`);  // Bytes transferred
  console.log(`Speed: ${progress.speed} bytes/s`);           // Current download speed
});
 
// Await the final result when the download finishes
const result = await download.completed;

How do I use chunked transfer for large files?


// Set a custom chunk size for large file downloads (default varies)
const result = await client.download.downloadFile({
  machine: 'my-server',
  url: 'https://example.com/huge-file.iso',
  destination: '/tmp/huge-file.iso',
  chunkSize: 1024 * 1024,   // Transfer in 1MB chunks
});

How do I cancel a download?


// Start a download that can be cancelled
const download = client.download.downloadFile({
  machine: 'my-server',
  url: 'https://example.com/large-file.bin',
  destination: '/tmp/large-file.bin',
});
 
// Cancel the download after 10 seconds
setTimeout(() => download.cancel(), 10000);
 
try {
  await download.completed;
} catch (err) {
  // Check if the error is a cancellation (not a real failure)
  if (err.code === 'CANCELLED') {
    console.log('Download was cancelled');
  }
}

What parameters does downloadFile() accept?

`downloadFile(options)`

Parameter	Type	Description
`options.machine`	`string`	Target machine
`options.url`	`string`	Source URL
`options.destination`	`string`	Destination path on remote machine
`options.chunkSize`	`number`	Chunk size in bytes
`options.headers`	`Record<string, string>`	Custom HTTP headers

`downloadUrl(options)`

Same as downloadFile but returns a simple promise without progress tracking.

Progress Event

Field	Type	Description
`percent`	`number`	Download progress (0–100)
`transferred`	`number`	Bytes transferred
`total`	`number`	Total bytes (if known)
`speed`	`number`	Speed in bytes/second