docker-cli-js

2.10.0 verified Sat Apr 25 auth: no javascript

Node.js wrapper for the Docker CLI that executes docker commands via child_process.exec, returning parsed output (raw, success, imageId, etc.) as a promise. Current stable version is 2.10.0 with TypeScript types included. Maintained by Quobject, the library wraps the Docker CLI tool — not the Docker SDK — and supports custom machines, working directories, and echo output. Useful for scripting Docker operations from Node without the Docker SDK, but inherently couples to the CLI availability and command syntax.

Common errors

error Error: spawn docker ENOENT ↓

cause Docker CLI not installed or not in PATH.

fix

Install Docker and ensure it's accessible from terminal.

error TypeError: env is not iterable ↓

cause Deprecated env option usage; custom environment passed incorrectly.

fix

Pass options with env as an object of key-value pairs, not an array.

error Cannot find module 'docker-cli-js' ↓

cause Package not installed or import path wrong.

fix

Run npm install docker-cli-js and use correct import as shown in imports section.

Warnings

gotcha Uses child_process.exec internally; vulnerable to command injection if user input is passed unsanitized. ↓

fix Sanitize or whitelist command parts; do not pass unsanitized user input.

breaking DockerOptions renamed from Options in v2.0.0 when rewritten to TypeScript. ↓

fix Use DockerOptions instead of Options, or import Options as alias.

breaking Promise-based API changed; removed callback style in v2.0.0. ↓

fix Use .then() or async/await; no longer supports callbacks.

deprecated Options class is deprecated in favor of DockerOptions; kept for backward compatibility. ↓

fix Use DockerOptions.

gotcha machineName: null uses local Docker; non-null expects Docker Machine name. If Docker Machine not set up, command may fail. ↓

fix Ensure Docker is accessible or set machineName to a valid machine.

Install

npm install docker-cli-js

yarn add docker-cli-js

pnpm add docker-cli-js

Imports

dockerCommand
wrong
```
const dockerCommand = require('docker-cli-js').dockerCommand
```
correct
```
import { dockerCommand } from 'docker-cli-js'
```
ESM import works; CommonJS require works with destructuring as shown in wrong pattern, but it's not wrong per se — just a style difference.

Docker

wrong

const Docker = require('docker-cli-js').Docker

correct

import { Docker } from 'docker-cli-js'

Both import styles are valid. Class-based API for promise chaining.

DockerOptions
wrong
```
const DockerOptions = require('docker-cli-js').Options
```
correct
```
import { DockerOptions } from 'docker-cli-js'
```
The older API exported 'Options' class; renamed to 'DockerOptions' in TypeScript rewrite. Both exist for backward compatibility.

Options

wrong

const Options = require('docker-cli-js').Options

correct

import { Options } from 'docker-cli-js'

Alias for DockerOptions, kept for backward compatibility.

Quickstart

Demonstrates async/await usage of dockerCommand with default options to list containers.

import { dockerCommand } from 'docker-cli-js';

async function main() {
  try {
    const result = await dockerCommand('ps', {
      machineName: null,
      currentWorkingDirectory: null,
      echo: false,
    });
    console.log('Containers:', result.raw);
  } catch (err) {
    console.error('Docker command failed:', err);
  }
}

main();