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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create
✓ import { create } from 'acme-dns-01-cli';
✗ const greenlockChallenge = require('acme-dns-01-cli');
The 'create' function is the primary way to initialize and configure the challenge handler. For CommonJS, it is accessed as a named property: `const { create } = require('acme-dns-01-cli');`
(CommonJS module access)
✓ const acmeDns01Cli = require('acme-dns-01-cli');
✗ import acmeDns01Cli from 'acme-dns-01-cli';
In CommonJS environments, requiring the module directly provides an object containing its exports. This module does not provide a default export for direct ES module default imports.
set (method)
✓ const handler = create({ debug: true }); handler.set(opts);
✗ import { set } from 'acme-dns-01-cli'; set(opts);
The 'set' and 'remove' methods are properties of the challenge handler object returned by calling `create()`, not direct exports from the main `acme-dns-01-cli` module itself. These methods are typically invoked internally by the ACME client (e.g., Greenlock).
This quickstart demonstrates how to integrate `acme-dns-01-cli` into a Greenlock instance as a DNS-01 challenge handler, initiating a certificate request that will prompt the user for manual DNS record updates.
import Greenlock from 'greenlock';
import { create as createDns01CliChallenge } from 'acme-dns-01-cli';
// Configure the acme-dns-01-cli challenge handler
const challengeConfig = createDns01CliChallenge({
debug: true // Enable debug output for the CLI handler
});
// Initialize Greenlock with the custom challenge handler
const greenlock = Greenlock.create({
package: {
name: 'my-greenlock-app',
version: '1.0.0',
},
configDir: './greenlock.d/', // Specify a configuration directory
maintainerEmail: 'your-email@example.com',
cluster: false, // Set to true for multi-process environments
challenges: {
'dns-01': challengeConfig // Register the interactive DNS-01 challenge
},
// Define how domains are approved (customize as needed)
approveDomains: async (opts) => {
console.log(`Greenlock is requesting approval for: ${opts.subject || opts.altnames.join(', ')}`);
// For acme-dns-01-cli, the manual interaction will occur via the challengeConfig
return opts;
},
});
// Function to request a certificate (this will trigger the CLI prompt)
async function obtainCertificate() {
const domainsToSecure = ['example.com', '*.example.com']; // Example domains
console.log(`Attempting to obtain certificate for: ${domainsToSecure.join(', ')}`);
try {
const cert = await greenlock.add({
subject: domainsToSecure[0], // Primary domain
altnames: domainsToSecure, // All domains including wildcard
email: 'your-email@example.com', // Email for renewal notices
});
console.log('Successfully obtained certificate:', cert);
} catch (err) {
console.error('Failed to obtain certificate:', err);
if (err.challenge && err.challenge.dnsHost && err.challenge.dnsAuthorization) {
console.warn(`Please verify the TXT record for ${err.challenge.dnsHost} with value ${err.challenge.dnsAuthorization} is correctly set.`);
}
}
}
// Execute the certificate acquisition process
obtainCertificate();
// In a real application, Greenlock would also manage a server
// to handle certificate renewals and serve HTTPS traffic.
// Example (requires 'greenlock-express'):
/*
import greenlockExpress from 'greenlock-express';
greenlockExpress.create({
package: greenlock.defaults.package,
configDir: greenlock.defaults.configDir,
maintainerEmail: greenlock.defaults.maintainerEmail,
cluster: greenlock.defaults.cluster,
challenges: greenlock.defaults.challenges,
approveDomains: greenlock.defaults.approveDomains,
// Add your server options here
}).listen(80, 443);
*/
acme-dns-01-cli --version
Errors
Common errors & fixes
TypeError: require(...).create is not a function
Incorrect module import/access for the 'create' function, or an incompatibility between Greenlock and acme-dns-01-cli versions.
fixEnsure you are using `const { create } = require('acme-dns-01-cli');` for CommonJS or `import { create } from 'acme-dns-01-cli';` for ES Modules. Verify your Greenlock version is compatible with acme-dns-01-cli v3.x (Greenlock v3.x+ is generally required). Error: Challenge verification failed.
The DNS TXT record was not correctly propagated or not set in time before the ACME server attempted verification.
fixDouble-check the exact DNS Host and DNS Key Authorization Digest provided by the CLI. Ensure the TXT record is published correctly and has propagated across DNS servers (use tools like `dig` or online DNS checkers). Wait a few minutes after setting the record before pressing Enter in the CLI.
ReferenceError: Greenlock is not defined
The Greenlock module was not imported or required correctly before use.
fixAdd `const Greenlock = require('greenlock');` for CommonJS or `import Greenlock from 'greenlock';` for ES Modules at the top of your file, ensuring Greenlock is installed (`npm install greenlock`). Audit
Dependencies
greenlockoptionalacme-dns-01-cli is designed to integrate as a challenge handler with Greenlock instances; specific version compatibility exists.