Registry / devops / dockermachine-cli-js

dockermachine-cli-js

library3.0.5jsnpmunverified

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.

devops

npm install dockermachine-cli-js

github ↗package ↗

INSTALL

IMPORT

SIG · DOCKERMACHINE-CLI-

dockermachine-cli-js

devopsjavascriptv3.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DockerMachine, Options

✓ import { DockerMachine, Options } from 'dockermachine-cli-js';

Preferred import for TypeScript and ESM environments.

DockerMachineCLI

✓ const DockerMachineCLI = require('dockermachine-cli-js');

✗ import DockerMachineCLI from 'dockermachine-cli-js';

CommonJS require pattern. The main export is an object containing `DockerMachine` and `Options`.

Options

✓ const options = new DockerMachineCLI.Options(...);

✗ const options = new Options(...);

When using CommonJS `require`, `Options` is a property of the main `DockerMachineCLI` export.

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.

import { DockerMachine, Options } from 'dockermachine-cli-js'; // Placeholder for configuration, replace with actual values or environment variables const config = { accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY' }; const keyValueObject = { 'driver': 'amazonec2', 'amazonec2-access-key': config.accessKeyId, 'amazonec2-secret-key': config.secretAccessKey, 'amazonec2-ami': 'ami-b59ce48f', // Example AMI, choose appropriate for your region 'amazonec2-region': 'ap-southeast-2', 'amazonec2-zone': 'a', 'amazonec2-instance-type': 't2.micro', 'amazonec2-root-size': 8 }; const options = new Options( /* keyValueObject */ keyValueObject, /* currentWorkingDirectory */ null ); const dockerMachine = new DockerMachine(options); console.log('Attempting to create a Docker Machine...'); dockerMachine.command('create my-test-machine') .then(function (data) { console.log('Machine creation command output:', data); return dockerMachine.command('ls'); }) .then(function (data) { console.log('List of Docker Machines:', data.machineList); // Clean up: Delete the created machine console.log('Attempting to remove the Docker Machine...'); return dockerMachine.command('rm -f my-test-machine'); }) .then(function (data) { console.log('Machine removal command output:', data); console.log('Cleanup complete.'); }) .catch(function (err) { console.error('An error occurred:', err); });

Debug

Known issues

gotchaThe `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.

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.

affects: >=1.0.0

breakingIn 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.

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' }`).

affects: >=3.0.2

breakingVersion 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.

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.

affects: >=2.0.0

Errors

Common errors & fixes

Error: spawn docker-machine ENOENT

The `docker-machine` command-line tool is not installed or is not accessible in the system's PATH environment variable.

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.

TypeError: DockerMachineCLI.Options is not a constructor

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.

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(...)`.

UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: ...

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.

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.

Upgrade

Version history

3.0.5latest on npm

Audit

Dependencies

docker-machinerequiredThis 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.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Quobject/dockermachine-cli-js ↗

packagehttps://www.npmjs.com/package/dockermachine-cli-js ↗