{"id":17056,"library":"resin-cli-form","title":"Balena CLI Form Interpreter","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/balena-io-modules/resin-cli-form","tags":["javascript","resin","form","cli","typescript"],"install":[{"cmd":"npm install resin-cli-form","lang":"bash","label":"npm"},{"cmd":"yarn add resin-cli-form","lang":"bash","label":"yarn"},{"cmd":"pnpm add resin-cli-form","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides visual components and rendering for the CLI form interaction.","package":"resin-cli-visuals","optional":false}],"imports":[{"note":"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`.","wrong":"const form = require('resin-cli-form');","symbol":"form","correct":"import * as form from 'resin-cli-form';"},{"note":"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.","wrong":"import form from 'resin-cli-form'; // then trying form.run()","symbol":"run","correct":"import { run } from 'resin-cli-form';"},{"note":"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.","wrong":"const { ask } = require('resin-cli-form');","symbol":"ask","correct":"import { ask } from 'resin-cli-form';"}],"quickstart":{"code":"import { run } from 'resin-cli-form';\n\nasync function configureDevice() {\n  try {\n    const answers = await run([\n      {\n        message: 'Network Type',\n        name: 'network',\n        type: 'list',\n        choices: ['ethernet', 'wifi']\n      },\n      {\n        message: 'WiFi SSID',\n        name: 'wifiSsid',\n        type: 'input',\n        when: { network: 'wifi' }\n      },\n      {\n        message: 'WiFi Key',\n        name: 'wifiKey',\n        type: 'input',\n        when: { network: 'wifi' }\n      }\n    ], {\n      override: {\n        // Example: pre-fill a value to skip the question\n        // wifiSsid: process.env.DEFAULT_WIFI_SSID ?? ''\n      }\n    });\n    console.log('Configuration complete. Answers:', answers);\n\n    if (answers.network === 'wifi') {\n      console.log(`Connecting to WiFi network: ${answers.wifiSsid} with key ${answers.wifiKey ? '*********' : '[no key provided]'}`);\n    }\n\n  } catch (error) {\n    console.error('Form execution failed:', error);\n  }\n}\n\nconfigureDevice();","lang":"typescript","description":"Demonstrates how to run a declarative CLI form with conditional questions using `form.run`, including an example of the `when` property."},"warnings":[{"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'`.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js runtime to version 20.0 or newer to use resin-cli-form v5.x.x.","message":"Node.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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Carefully define `when` conditions; for 'OR' logic or more complex scenarios, consider using multiple questions or re-evaluating the form structure dynamically.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update any saved repository URLs or links to `https://github.com/balena-io-modules/resin-cli-form` for the latest information and contributions.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `const form = require('resin-cli-form');` to `import * as form from 'resin-cli-form';` or `import { run, ask } from 'resin-cli-form';`.","cause":"Attempting to use CommonJS `require()` to import `resin-cli-form`, which is now an ES Module.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()"},{"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`).","cause":"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).","error":"TypeError: form.run is not a function"},{"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.","cause":"Running `resin-cli-form` v5.x on an unsupported Node.js version.","error":"Error: The 'engines' field in package.json specifies an unsupported Node.js version. Required: '>=20.0.0'. Found: 'v18.17.0'."}],"ecosystem":"npm","meta_description":null}