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, terminal 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.

Every prompt must have the same basic fields:

  • 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 on the terminal 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.

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 on the terminal 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 on the terminal.

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 terminal.

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.

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. On a terminal, 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.

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.

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"]
    })

    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.

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}`)
}