Node.js Prompts
Prompt interface overview
Each user prompt is configured in a JavaScript definition object. One or more of these objects can be passed to a ux.prompt
call to obtain user input; the prompts will occur in sequence automatically.
User input will be accepted by a variety of means depending on the environment where the code is running. Locally, command-line input is used by default, with command-line arguments seamlessly substituted where appropriate. In a remote environment, this will be a remote interface such as a Slack channel.
Common parameters
Every prompt must have the same common parameters:
type
(string): the prompt type, as described below. Currently
valid types areinput
number
secret
password
confirm
list
autocomplete
checkbox
editor
datetime
name
(string): The name of the prompt, which should be unique within the program. The kebab-case version of this name is used as the command-line argument name, for example, the prompt with namebaseBranch
can have its value specified as--base-branch master
. The return value ofux.prompt
will use this name as the key for the returned value for this prompt.message
(string): The prompt for the user to be displayed when input is necessary
There is also one optional parameter that is common to all prompt types:
flag
(string): an alias for thename
that can be used as a command line argument. Can be a single character, which can then be used as in-b master
.
input
prompt
The input
prompt type requests a single-line string from the user. Along with the common parameters above, it can accept the following optional parameters:
default
(string): a default value to be provided to the command-line and accepted if the user just presses return.allowEmpty
(boolean): Set to true to accept empty input to this prompt. Defaults to requiring non-empty input.
As Slack does not allow users to send blank messages, the default
and allowEmpty
arguments will not register in Slack.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { opinion } = await ux.prompt({
type: "input",
name: "opinion",
message: "What do you think of Typescript?",
flag: "o",
default: "I don't know"
})
await ux.print(`You think "${opinion}" about Typescript`)
}
number
prompt
The number
prompt requests an integer from the user. Along with the common parameters above, it can accept the following optional parameters:
default
(number): a default value to be provided to the command-line and accepted if the user just presses return.minimum
(number): a minimum value for the input numbermaximum
(number): a maximum value for the input number
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { count } = await ux.prompt({
type: "number",
name: "count",
message: "How many hoorays do you want?",
flag: "c",
default: 3,
minimum: 0,
maximum: 20
})
for (let i = 0; i < count; i++) {
await ux.print("Hooray!")
}
}
secret
prompt
The secret
prompt type will request a secret from the user. The user can respond to this prompt by entering a value, or, if they have a secrets provider configured, with a value from their team secret store. Secrets will be entered in the clear in the command-line.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { sshKey } = await ux.prompt({
type: "secret",
name: "sshKey",
message: "What SSH private key do you want to use?"
})
await ux.print(`Your private key has ${sshKey.length} characters. Isn't that interesting?`)
}
password
prompt
The password
prompt type will request a password from the user. The user can respond to this prompt by entering a value, or, if they have a secrets provider configured, with a value from their team password store. Passwords will be hidden in the command-line.
Along with the common parameters above, the password prompt takes the following optional parameter:
confirm
(boolean): Set to true to require the user to confirm the choice of password. Defaults to false.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { password } = await ux.prompt({
type: "password",
name: "password",
message: "What new password would you like to use?",
confirm: true
})
if (password.length < 6) {
await ux.print(`I don't think you want a password as short as ${password}`)
} else {
await ux.print("Password length acceptable")
}
}
confirm
prompt
The confirm
prompt type requests a yes/no answer to the user. Confirm prompts can be matched with bare command-line arguments, such as "--verbose" or "-V". Along with the common parameters above, the confirm prompt takes the following optional parameter:
default
(boolean): The value selected if the user presses return at the prompt. Defaults to false.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { verbose } = await ux.prompt({
type: "confirm",
name: "verbose",
flag: "V",
message: "Do you want to run in verbose mode?"
})
if (verbose) {
await ux.print("You have reached the end of this example demonstrating the confirm prompt type in the Ops SDK.")
} else {
await ux.print("Done.")
}
}
list
prompt
The list
prompt type asks the user to select a single item from a list of choices. Along with the common parameters above, the list prompt takes the following parameters:
choices
(string[]) required: The list of choices to be presented to the user.default
(string|number) optional: The default selection from the list. Can be passed as either the default value or the index of the default value.
In Slack, the list
prompt will produce a drop down menu to select from. Users can also enter their desired choice in the text box to make a selection.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { platform } = await ux.prompt({
type: "list",
name: "platform",
message: "What cloud platform would you like to deploy to?",
choices: ["AWS", "Google Cloud", "Azure"],
default: "AWS"
})
await ux.print(`Preparing to deploy to ${platform}`)
}
autocomplete
prompt
The autocomplete
prompt type asks the user to select a single item from a list of choices. In the command-line, it allows the user to select the item by typing with fuzzy autocomplete. Along with the common parameters above, the autocomplete prompt takes the following parameters:
choices
(string[]) required: The list of choices to be presented to the user.default
(string|number) optional: The default selection from the list. Can be passed as either the default value or the index of the default value.
The autocomplete
prompt type will function identical to the list
prompt type in Slack.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { province } = await ux.prompt({
type: "autocomplete",
name: "province",
message: "To which province do you want to send your letter?",
choices: ["Alberta", "British Columbia", "Manitoba", "New Brunswick","Newfoundland and Labrador", "Nova Scotia", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan"],
default: 1
})
await ux.print(`Preparing address label for ${province}`)
}
checkbox
prompt
The checkbox
prompt type asks the user to select multiple item from a list of choices. Along with the common parameters above, the checkbox prompt takes the following parameters:
choices
(string[]) required: The list of choices to be presented to the user.default
(string|number[]) optional: The default selection from the list. Can be passed as either the default value or the index of the default value.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { tools } = await ux.prompt({
type: "checkbox",
name: "tools",
message: "Which interpreters would you like to have included in your OS image?",
choices: ["Lua", "Node.js", "Perl", "Python 2", "Python 3", "Raku", "Ruby"],
default: [1]
})
for (const tool of tools) {
await ux.print(`Adding ${tool}`)
await ux.wait(500)
}
}
editor
prompt
The editor
prompt type asks the user for a multi-line text input. In a local environment, it will start the nano
editor inside the container. Along with the common parameters above, the list prompt takes the following optional parameter:
default
(string|number): The default text to appear in the editor when it opens. Can be a template.
Currently, the default
argument will not appear in Slack.
Example:
import { ux } from '@cto.ai/sdk'
const template = `Features:
Fixes:
Chores:
`
const main = async () => {
const { notes } = await ux.prompt({
type: "editor",
name: "notes",
message: "Please enter your release notes",
default: template
})
await ux.print(`Your release notes are ${notes}`)
}
datetime
prompt
The datetime
prompt type asks the user for a date and/or time. Along with the common parameters above, the list prompt takes the following optional parameters:
variant
("date"
|"time"
|"datetime"
) - specifies which time information to prompt for, either a date (day/month/year) or a time (hour/minute/second), or both. Default is"datetime"
.default
(string|Date) - The time to initialize the prompt with. If not specified, will default to the current time.minimum
(string|Date) - The minimum time to permit in the prompt.maximum
(string|Date) - The maximum time to permit in the prompt.
If specified as strings, the default
, minimum
and maximum
must be in RFC 3339 format.
Example:
import { ux } from '@cto.ai/sdk'
const main = async () => {
const { nextRun } = await ux.prompt({
type: "datetime",
name: "nextRun",
message: "When do you want to run the code next?",
minimum: new Date()
})
await ux.print(`Your code will next run at ${nextRun}`)
}
🚀 What's next?
- If you want to explore the options offered by our SDKs, go to the Node.js SDK page
- To learn more about the UX options available for you, please go to Node.js UX page.
- Add Secrets Management page to the Password and Secrets prompts.