resin-cli-form

library5.0.1jsnpmunverified

resin-cli-form is a JavaScript/TypeScript library designed to interpret and execute declarative form definitions within command-line interfaces. It enables developers to construct interactive CLI forms with features like conditional questions using a `when` property, where subsequent questions are only presented if specific conditions based on prior answers are met. The current stable version is 5.0.1, released in February 2026. The project has undergone significant modernization in its recent major releases, notably switching from CoffeeScript to TypeScript, adopting ES Modules, and migrating to `async/await` in version 5.0.0. Its release cadence shows active development and maintenance, with major architectural shifts around 2025-2026. This library is a specialized tool for building structured, interactive CLI experiences, particularly within the Balena.io ecosystem, providing a robust abstraction for complex user input flows.

devops web-framework

npm install resin-cli-form

github ↗package ↗

INSTALL

IMPORT

SIG · RESIN-CLI-FORM

resin-cli-form

devopsjavascriptv5.0.1

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.

form

✓ import * as form from 'resin-cli-form';

✗ const form = require('resin-cli-form');

Since v5.0.0, the library is ESM-only. The main functions `run` and `ask` are exposed as properties of a default or namespace import, typically accessed as `form.run` or `form.ask`.

run

✓ import { run } from 'resin-cli-form';

✗ import form from 'resin-cli-form'; // then trying form.run()

While `import * as form` is common, direct named imports for `run` and `ask` are also supported in v5.0.0 and later. Ensure you use named imports for individual functions.

ask

✓ import { ask } from 'resin-cli-form';

✗ const { ask } = require('resin-cli-form');

Similar to `run`, `ask` is available as a named export. Avoid CommonJS `require` syntax as it will fail due to the library being ESM-only since v5.

Demonstrates how to run a declarative CLI form with conditional questions using `form.run`, including an example of the `when` property.

import { run } from 'resin-cli-form'; async function configureDevice() { try { const answers = await run([ { message: 'Network Type', name: 'network', type: 'list', choices: ['ethernet', 'wifi'] }, { message: 'WiFi SSID', name: 'wifiSsid', type: 'input', when: { network: 'wifi' } }, { message: 'WiFi Key', name: 'wifiKey', type: 'input', when: { network: 'wifi' } } ], { override: { // Example: pre-fill a value to skip the question // wifiSsid: process.env.DEFAULT_WIFI_SSID ?? '' } }); console.log('Configuration complete. Answers:', answers); if (answers.network === 'wifi') { console.log(`Connecting to WiFi network: ${answers.wifiSsid} with key ${answers.wifiKey ? '*********' : '[no key provided]'}`); } } catch (error) { console.error('Form execution failed:', error); } } configureDevice();

Debug

Known issues

breakingVersion 5.0.0 converted the entire library to TypeScript and ES Modules. CommonJS `require()` syntax is no longer supported. All imports must use ESM `import` statements.

fix

Migrate all `require()` calls to `import` statements. For example, `const form = require('resin-cli-form')` becomes `import * as form from 'resin-cli-form'` or `import { run, ask } from 'resin-cli-form'`.

affects: >=5.0.0

breakingVersion 5.0.0 dropped the Bluebird promise library and switched to native `async/await` for asynchronous operations. While the public API still returns Promises, internal code and any direct Bluebird interactions in calling code will need adjustment.

fix

Ensure your environment supports `async/await`. If you were relying on Bluebird-specific Promise features, refactor to use native Promise methods or compatible utility libraries.

affects: >=5.0.0

breakingNode.js version requirements have progressively increased. Version 3.0.0 dropped support for Node.js versions below 18. Version 4.0.0 dropped support for Node.js 18. Version 5.0.0 and above now require Node.js 20.0 or higher.

fix

Upgrade your Node.js runtime to version 20.0 or newer to use resin-cli-form v5.x.x.

affects: >=3.0.0

gotchaThe `when` property for conditional questions expects an object where keys are answer names and values are the required answer for the condition to be true. Complex logical operations (AND, OR) are handled by defining multiple key-value pairs (AND) or structuring forms differently.

fix

Carefully define `when` conditions; for 'OR' logic or more complex scenarios, consider using multiple questions or re-evaluating the form structure dynamically.

affects: >=1.0.0

breakingThe project updated its GitHub organization from `resin-io-modules` to `balena-io-modules`. While npm package name remains `resin-cli-form`, be aware of updated repository and homepage URLs for contributions or issue reporting.

fix

Update any saved repository URLs or links to `https://github.com/balena-io-modules/resin-cli-form` for the latest information and contributions.

affects: >=5.0.1

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

Attempting to use CommonJS `require()` to import `resin-cli-form`, which is now an ES Module.

fix

Change `const form = require('resin-cli-form');` to `import * as form from 'resin-cli-form';` or `import { run, ask } from 'resin-cli-form';`.

TypeError: form.run is not a function

Incorrect import syntax (e.g., trying to use `form.run` after a default import of a non-object, or a CJS import in an ESM context).

fix

Ensure you are using `import * as form from 'resin-cli-form';` or `import { run, ask } from 'resin-cli-form';` for named exports, and that your file is treated as an ESM module (e.g., `.mjs` extension or `"type": "module"` in `package.json`).

Error: The 'engines' field in package.json specifies an unsupported Node.js version. Required: '>=20.0.0'. Found: 'v18.17.0'.

Running `resin-cli-form` v5.x on an unsupported Node.js version.

fix

Upgrade your Node.js runtime to version 20.0 or higher. You can use `nvm` (Node Version Manager) to easily switch Node.js versions.

Upgrade

Version history

5.0.1latest on npm

Audit

Dependencies

resin-cli-visualsrequiredProvides visual components and rendering for the CLI form interaction.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/balena-io-modules/resin-cli-form ↗

packagehttps://www.npmjs.com/package/resin-cli-form ↗