Node.js SDK: prompts

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 are - input - 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 name baseBranch can have its value specified as --base-branch master. The return value of ux.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 the name 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 number
• maximum (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}`)
}