summary |
---|
Prompts are terminal widgets for user input, using the @poppinss/prompts package. They support various types like input, password, and select, and are designed for easy testing integration. |
Prompts are interactive terminal widgets you can use to accept user input. Ace prompts are powered by the @poppinss/prompts package, which supports the following prompt types.
- input
- list
- password
- confirm
- toggle
- select
- multi-select
- autocomplete
Ace prompts are built with testing in mind. When writing tests, you may trap prompts and respond to them programmatically.
See also: Testing ace commands
You may display prompts using the this.prompt
property available on all Ace commands.
import { BaseCommand } from '@adonisjs/core/ace'
export default class GreetCommand extends BaseCommand {
async run() {
const modelName = await this.prompt.ask('Enter the model name')
console.log(modelName)
}
}
Following is the list of options accepted by prompts. You may reference this table as the single source of truth.
Option | Accepted by | Description |
|
All prompts |
The default value to use when no value is entered. In the case of |
|
All prompts |
The unique name for the prompt |
|
All prompts |
The hint text to display next to the prompt |
|
All prompts |
Transform the prompt return value. The input value of the {
result(value) {
return value.toUpperCase()
}
} |
|
All prompts |
Live format the input value as the user types. The formatting is only applied to the CLI output, not the return value. {
format(value) {
return value.toUpperCase()
}
} |
|
All prompts |
Validate the user input. Returning {
format(value) {
return value.length > 6
? true
: 'Model name must be 6 characters long'
}
} |
|
|
Limit the number of options to display. You will have to scroll to see the rest of the options. |
You may render the prompt to accept text input using the prompt.ask
method. The method accepts the prompt message as the first parameter and the options object as the second parameter.
await this.prompt.ask('Enter the model name')
// Validate input
await this.prompt.ask('Enter the model name', {
validate(value) {
return value.length > 0
}
})
// Default value
await this.prompt.ask('Enter the model name', {
default: 'User'
})
As the name suggests, the masked input prompt masks the user input in the terminal. You may display the masked prompt using the prompt.secure
method.
The method accepts the prompt message as the first parameter and the options object as the second parameter.
await this.prompt.secure('Enter account password')
await this.prompt.secure('Enter account password', {
validate(value) {
return value.length < 6
? 'Password must be 6 characters long'
: true
}
})
You may display a list of choices for a single selection using the prompt.choice
method. The method accepts the following parameters.
- Prompt message.
- An array of choices.
- Optional options object.
await this.prompt.choice('Select package manager', [
'npm',
'yarn',
'pnpm'
])
To mention a different display value, you can define options as objects. The name
property is returned as the prompt result, and the message
property is displayed in the terminal.
await this.prompt.choice('Select database driver', [
{
name: 'sqlite',
message: 'SQLite'
},
{
name: 'mysql',
message: 'MySQL'
},
{
name: 'pg',
message: 'PostgreSQL'
}
])
You may use the prompt.multiple
method to allow multiple selections in the choices list. The accepted parameters are the same as the choice
prompt.
await this.prompt.multiple('Select database drivers', [
{
name: 'sqlite',
message: 'SQLite'
},
{
name: 'mysql',
message: 'MySQL'
},
{
name: 'pg',
message: 'PostgreSQL'
}
])
You can display a confirmation prompt with Yes/No
options using the prompt.confirm
method. The method accepts the prompt message as the first parameter and the options object as the second parameter.
The confirm
prompt returns a boolean value.
const deleteFiles = await this.prompt.confirm(
'Want to delete all files?'
)
if (deleteFiles) {
}
To customize the Yes/No
options display value, you may use the prompt.toggle
method.
const deleteFiles = await this.prompt.toggle(
'Want to delete all files?',
['Yup', 'Nope']
)
if (deleteFiles) {
}
The autocomplete
prompt is a combination of the select and the multi-select prompt, but with the ability to fuzzy search the choices.
const selectedCity = await this.prompt.autocomplete(
'Select your city',
await getCitiesList()
)