Build guided, genie-style command-line wizards in a few lines. CLI Genie wraps Inquirer with what most wizards need:
- π§ 10 prompt types: text, password, number, confirm, select, rawlist, checkbox, expand, search, editor
- π Conditional and dynamic steps:
when,message,defaultandchoicescan depend on earlier answers - π Review screen where users can check and change any answer before finishing
- π€ Non-interactive mode for CI and scripts: answers from flags, env vars or code, with type coercion and validation
- πͺ Hooks:
transform,onAnswer,onComplete,onCancel - π JSON wizards and a
cli-geniecommand, so no code is needed - π¨ Genie theme, progress counter, clean Ctrl+C handling
- π¦ Written in TypeScript, ships ESM + CommonJS with type definitions
Requires Node.js 22.13+ or 24+.
npm install cli-genieimport { CliGenie, confirm, select, text } from 'cli-genie';
// or: const { CliGenie, confirm, select, text } = require('cli-genie');
const genie = new CliGenie({
title: 'Welcome to CLI Genie',
summary: true,
steps: [
text({ name: 'name', message: 'What is your name?', required: true }),
confirm({ name: 'chooseColor', message: 'Do you want to choose a colour?' }),
select({
name: 'color',
message: (answers) => `Pick a colour, ${answers.name}:`,
choices: ['Red', 'Green', 'Blue'],
when: (answers) => answers.chooseColor,
}),
],
});
const answers = await genie.run();
// { name: 'Ben', chooseColor: true, color: 'Green' }There are more examples in examples/.
Each step builder takes the matching Inquirer prompt options plus these CLI Genie options:
| Option | Type | Description |
|---|---|---|
name |
string |
Required. Key the answer is stored under. |
message |
string | (answers) => string |
Required. The question. |
default |
value | (answers) => value |
Default answer (also used in non-interactive mode). |
when |
(answers) => boolean |
Only ask when this returns true. |
validate |
(value, answers) => true | string |
Return true or an error message. Receives earlier answers. |
transform |
(value, answers) => any |
Change the answer before it is stored. |
label |
string |
Label for the review screen (defaults to the message). |
theme |
object |
Per-step Inquirer theme overrides. |
| Builder | Answer type | Notes |
|---|---|---|
text() |
string |
required: true rejects empty input. |
password() |
string |
mask: true shows * characters. |
number() |
number |
min, max, step. |
confirm() |
boolean |
|
select() |
choice | choices may be a function of the answers. Supports Separator. |
rawlist() |
choice | Numbered list. |
checkbox() |
array |
default is the list of pre-checked values. validate gets the values. |
expand() |
choice | Choices have a key; default is a key. |
search() |
choice | source(term, { signal, answers }) returns choices. |
editor() |
string |
Opens $EDITOR. |
new CliGenie({
steps, // Step[]
title, // banner shown before the first question
progress: true, // show "(2/5)" before each question
summary: false, // true | { title?, allowEdit?, format?(value, step) }
theme: 'genie', // 'genie' | 'plain' | custom Inquirer theme object
initialAnswers: {}, // pre-filled answers; matching steps are skipped
interactive: 'auto', // true | false | 'auto' (prompt only when stdin is a TTY)
hooks: { onAnswer, onComplete, onCancel },
context: { input, output, signal }, // passed to every prompt
});With summary: true, the genie lists every answer at the end. The user can confirm,
change any answer or start over. When an answer changes, steps that depend on it
are asked or removed automatically.
import { CliGenie, fromArgv, fromEnv } from 'cli-genie';
const genie = new CliGenie({
steps,
// `--first-name=Ben`, `--no-git`, `GENIE_FIRST_NAME=Ben` all match a step named `firstName`
initialAnswers: { ...fromEnv('GENIE_'), ...fromArgv() },
});Supplied answers are converted to the step's type ("42" β 42, "yes" β true,
"a,b" β ['a', 'b'], and a choice's name or value β its value) and then validated.
When there's no TTY (CI, piped input) or interactive: false is set, any step without
a supplied answer uses its default. If it has no default, a MissingAnswerError is thrown.
Pressing Ctrl+C (or aborting context.signal) rejects run() with a GenieCancelledError
that contains the answers collected so far:
import { isCancelled } from 'cli-genie';
try {
await genie.run();
} catch (error) {
if (isCancelled(error)) process.exit(130);
throw error;
}Other errors: MissingAnswerError and InvalidAnswerError, both subclasses of GenieError.
interface Order {
size: 'small' | 'large';
extras: string[];
}
const order = await genie.run<Order>();Define a wizard as JSON. Functions are replaced by declarative options:
{
"title": "Pizza order",
"summary": true,
"steps": [
{
"type": "text",
"name": "email",
"message": "Email",
"pattern": "@",
"patternMessage": "Invalid email"
},
{ "type": "select", "name": "size", "message": "Size", "choices": ["small", "large"] },
{ "type": "confirm", "name": "delivery", "message": "Delivery?" },
{ "type": "text", "name": "address", "message": "Address", "when": { "delivery": true } }
]
}when matches when every listed answer is equal; an array value means "any of".
search steps aren't available in JSON because they need a function.
Run it from code with await loadWizard('wizard.json') or defineWizard(object), or from the shell:
npx cli-genie wizard.json # prompts on stderr, answers as JSON on stdout
npx cli-genie wizard.json --size=large # pre-fill answers
npx cli-genie wizard.json --non-interactive # never prompt (CI)
ORDER=$(npx cli-genie wizard.json) # capture the answersv1 code still works, with deprecation warnings in your editor:
const { CliGenie, textInputPrompt, listPrompt } = require('cli-genie');
new CliGenie([textInputPrompt('Name?', 'name'), listPrompt('Colour?', 'color', ['Red'])]).run();Breaking changes in 2.0:
- Node.js 22.13+ is required.
run()resolves with the answers and no longer prints them.- Errors are thrown (as
GenieErrorsubclasses) instead of being logged withprocess.exitCode = 1. whennow receives the earlier answers. In v1 it always received{}, so conditional questions never appeared.stylingis merged into the Inquirer theme.promptLibraryis ignored.
See CONTRIBUTING.md.
MIT, see LICENSE.
