{"id":16980,"library":"dockermachine-cli-js","title":"Docker Machine CLI Wrapper","description":"dockermachine-cli-js is a Node.js wrapper library that provides a programmatic interface for interacting with the `docker-machine` command-line tool. It abstracts the execution of `docker-machine` commands, offering both Promise-based and callback-style APIs for convenience. The current stable version is 3.0.5. While releases appear infrequent, the project has seen recent updates in the 3.x series, indicating active maintenance. A key differentiator is its ability to parse the output of commands like `ls` into structured JavaScript objects, rather than just returning raw string output. It also ships with TypeScript type definitions, enabling a robust development experience for TypeScript users. This library is specifically useful for automating `docker-machine` provisioning and management tasks within Node.js applications, offering a more structured approach than direct `child_process` execution. A crucial prerequisite is the external installation and availability of the `docker-machine` CLI tool on the system's PATH, as this library acts as a thin wrapper around it.","status":"active","version":"3.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/Quobject/dockermachine-cli-js","tags":["javascript","docker","dockermachine","docker-machine","docker-machine cli","typescript"],"install":[{"cmd":"npm install dockermachine-cli-js","lang":"bash","label":"npm"},{"cmd":"yarn add dockermachine-cli-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add dockermachine-cli-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a wrapper for the `docker-machine` CLI tool, which must be installed globally and accessible in the system's PATH for the wrapper to function.","package":"docker-machine","optional":false}],"imports":[{"note":"Preferred import for TypeScript and ESM environments.","symbol":"DockerMachine, Options","correct":"import { DockerMachine, Options } from 'dockermachine-cli-js';"},{"note":"CommonJS require pattern. The main export is an object containing `DockerMachine` and `Options`.","wrong":"import DockerMachineCLI from 'dockermachine-cli-js';","symbol":"DockerMachineCLI","correct":"const DockerMachineCLI = require('dockermachine-cli-js');"},{"note":"When using CommonJS `require`, `Options` is a property of the main `DockerMachineCLI` export.","wrong":"const options = new Options(...);","symbol":"Options","correct":"const options = new DockerMachineCLI.Options(...);"}],"quickstart":{"code":"import { DockerMachine, Options } from 'dockermachine-cli-js';\n\n// Placeholder for configuration, replace with actual values or environment variables\nconst config = {\n  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID',\n  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY'\n};\n\nconst keyValueObject = {\n  'driver': 'amazonec2',\n  'amazonec2-access-key': config.accessKeyId,\n  'amazonec2-secret-key': config.secretAccessKey,\n  'amazonec2-ami': 'ami-b59ce48f', // Example AMI, choose appropriate for your region\n  'amazonec2-region': 'ap-southeast-2',\n  'amazonec2-zone': 'a',\n  'amazonec2-instance-type': 't2.micro',\n  'amazonec2-root-size': 8\n};\n\nconst options = new Options(\n  /* keyValueObject */ keyValueObject,\n  /* currentWorkingDirectory */ null\n);\n\nconst dockerMachine = new DockerMachine(options);\n\nconsole.log('Attempting to create a Docker Machine...');\n\ndockerMachine.command('create my-test-machine')\n  .then(function (data) {\n    console.log('Machine creation command output:', data);\n    return dockerMachine.command('ls');\n  })\n  .then(function (data) {\n    console.log('List of Docker Machines:', data.machineList);\n    // Clean up: Delete the created machine\n    console.log('Attempting to remove the Docker Machine...');\n    return dockerMachine.command('rm -f my-test-machine');\n  })\n  .then(function (data) {\n    console.log('Machine removal command output:', data);\n    console.log('Cleanup complete.');\n  })\n  .catch(function (err) {\n    console.error('An error occurred:', err);\n  });\n","lang":"typescript","description":"This quickstart demonstrates how to initialize `DockerMachine` with AWS EC2 driver options, create a new Docker Machine, list existing machines, and then clean up by removing the created machine, using TypeScript and Promises."},"warnings":[{"fix":"Install `docker-machine` via official Docker documentation for your operating system (e.g., Docker Desktop or standalone installation). Verify installation by running `docker-machine version` in your terminal.","message":"The `docker-machine` command-line tool must be installed separately on the system where this Node.js package is run. This package is a wrapper, not an installer or bundler, of the `docker-machine` CLI. Ensure it's in your system's PATH.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that the first argument passed to the `Options` constructor is an object containing key-value pairs representing `docker-machine` command line flags (e.g., `{ 'driver': 'amazonec2', 'amazonec2-access-key': 'XYZ' }`).","message":"In version 3.0.2, the constructor for `Options` was changed to directly accept a `keyValueObject` as its first argument. Previous versions might have used a different structure or relied on implicit argument handling.","severity":"breaking","affected_versions":">=3.0.2"},{"fix":"For TypeScript projects, use `import { DockerMachine, Options } from 'dockermachine-cli-js';`. For CommonJS, `const DockerMachineCLI = require('dockermachine-cli-js');` should still work, but be aware that `Options` and `DockerMachine` are properties of the exported object.","message":"Version 2.0 introduced TypeScript support. While this generally improves type safety, it might have involved changes to the module's internal structure or export patterns. Users migrating from pre-2.0 versions might need to update their import statements or how they access `DockerMachineCLI` components, especially in TypeScript projects.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `docker-machine` on your system according to the official Docker documentation. After installation, verify it's available by running `docker-machine version` in your terminal. If installed but not found, ensure its executable directory is added to your system's PATH.","cause":"The `docker-machine` command-line tool is not installed or is not accessible in the system's PATH environment variable.","error":"Error: spawn docker-machine ENOENT"},{"fix":"For TypeScript/ESM, use named imports: `import { DockerMachine, Options } from 'dockermachine-cli-js';` then `new Options(...)`. For CommonJS, ensure `const DockerMachineCLI = require('dockermachine-cli-js');` is used and then `new DockerMachineCLI.Options(...)`.","cause":"This error typically occurs when attempting to instantiate `Options` directly from `DockerMachineCLI` in an ESM context where named imports are expected, or if an older CommonJS pattern is mixed with newer ESM imports.","error":"TypeError: DockerMachineCLI.Options is not a constructor"},{"fix":"Always append a `.catch(error => { console.error('Command failed:', error); })` to your `dockerMachine.command()` calls to properly handle errors and prevent unhandled promise rejections.","cause":"The Promise returned by `dockerMachine.command()` was not handled with a `.catch()` block, leading to an unhandled rejection if the underlying `docker-machine` command fails.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: ..."}],"ecosystem":"npm","meta_description":null}