{"id":18279,"library":"docker-cli-js","title":"docker-cli-js","description":"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.","status":"active","version":"2.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/Quobject/docker-cli-js","tags":["javascript","docker","docker cli","typescript"],"install":[{"cmd":"npm install docker-cli-js","lang":"bash","label":"npm"},{"cmd":"yarn add docker-cli-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add docker-cli-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Polyfills for older Node.js versions (used since 2.1.0 rewrite)","package":"core-js","optional":false}],"imports":[{"note":"ESM import works; CommonJS require works with destructuring as shown in wrong pattern, but it's not wrong per se — just a style difference.","wrong":"const dockerCommand = require('docker-cli-js').dockerCommand","symbol":"dockerCommand","correct":"import { dockerCommand } from 'docker-cli-js'"},{"note":"Both import styles are valid. Class-based API for promise chaining.","wrong":"const Docker = require('docker-cli-js').Docker","symbol":"Docker","correct":"import { Docker } from 'docker-cli-js'"},{"note":"The older API exported 'Options' class; renamed to 'DockerOptions' in TypeScript rewrite. Both exist for backward compatibility.","wrong":"const DockerOptions = require('docker-cli-js').Options","symbol":"DockerOptions","correct":"import { DockerOptions } from 'docker-cli-js'"},{"note":"Alias for DockerOptions, kept for backward compatibility.","wrong":"const Options = require('docker-cli-js').Options","symbol":"Options","correct":"import { Options } from 'docker-cli-js'"}],"quickstart":{"code":"import { dockerCommand } from 'docker-cli-js';\n\nasync function main() {\n  try {\n    const result = await dockerCommand('ps', {\n      machineName: null,\n      currentWorkingDirectory: null,\n      echo: false,\n    });\n    console.log('Containers:', result.raw);\n  } catch (err) {\n    console.error('Docker command failed:', err);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates async/await usage of dockerCommand with default options to list containers."},"warnings":[{"fix":"Sanitize or whitelist command parts; do not pass unsanitized user input.","message":"Uses child_process.exec internally; vulnerable to command injection if user input is passed unsanitized.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use DockerOptions instead of Options, or import Options as alias.","message":"DockerOptions renamed from Options in v2.0.0 when rewritten to TypeScript.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use .then() or async/await; no longer supports callbacks.","message":"Promise-based API changed; removed callback style in v2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use DockerOptions.","message":"Options class is deprecated in favor of DockerOptions; kept for backward compatibility.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Ensure Docker is accessible or set machineName to a valid machine.","message":"machineName: null uses local Docker; non-null expects Docker Machine name. If Docker Machine not set up, command may fail.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install Docker and ensure it's accessible from terminal.","cause":"Docker CLI not installed or not in PATH.","error":"Error: spawn docker ENOENT"},{"fix":"Pass options with env as an object of key-value pairs, not an array.","cause":"Deprecated env option usage; custom environment passed incorrectly.","error":"TypeError: env is not iterable"},{"fix":"Run `npm install docker-cli-js` and use correct import as shown in imports section.","cause":"Package not installed or import path wrong.","error":"Cannot find module 'docker-cli-js'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}