ask-user

NAME

ask-user - prompt the user for text input or selection

SYNOPSIS

state-name:
  tool: ask-user
  arguments:
    question: <prompt-text>
    multiline: <boolean>        # optional
    options: <option-list>      # optional
    allow-custom: <boolean>     # optional

DESCRIPTION

The ask-user tool displays a prompt and waits for user input. It supports single-line text, multi-line text, and selection from predefined options.

The tool is interactive and requires a terminal. It cannot be used in parallel blocks or when stdin is redirected.

ARGUMENTS

Argument	Required	Default	Description
`question`	Yes	-	The prompt to display
`multiline`	No	`false`	Enable multi-line input
`options`	No	-	List of choices for selection
`allow-custom`	No	`false`	Allow custom input when using options

Options Format

Options can be simple strings or structured with descriptions:

# Simple options
options:
  - "yes"
  - "no"

# With descriptions
options:
  - value: "dev"
    description: "Development environment"
  - value: "prod"
    description: "Production environment"

EXIT CODES

Code	Meaning
`0`	Input received
`130`	User cancelled (Ctrl+C)

OUTPUT

The user’s input is captured when output is specified:

get-name:
  tool: ask-user
  arguments:
    question: "What is your name?"
  output: var(name)

EXAMPLES

Simple Text Input

get-name:
  tool: ask-user
  arguments:
    question: "Enter your name:"
  output: var(user_name)

Multi-line Input

get-description:
  tool: ask-user
  arguments:
    question: "Enter the feature description (press Enter twice to finish):"
    multiline: true
  output: var(description)

Selection from Options

choose-env:
  tool: ask-user
  arguments:
    question: "Select deployment environment:"
    options:
      - value: "development"
        description: "Local development server"
      - value: "staging"
        description: "Pre-production testing"
      - value: "production"
        description: "Live production servers"
  output: var(environment)

With Custom Option Allowed

choose-branch:
  tool: ask-user
  arguments:
    question: "Select branch to deploy:"
    options:
      - "main"
      - "develop"
      - "release"
    allow-custom: true
  output: var(branch)

Handling Cancellation

get-confirmation:
  tool: ask-user
  arguments:
    question: "Proceed with deployment?"
    options:
      - "yes"
      - "no"
  output: var(confirm)
  on-error:
    130: user-cancelled
  next: check-confirmation

user-cancelled:
  tool: bash
  arguments:
    command: echo "Deployment cancelled by user"

Conditional Flow Based on Input

ask-action:
  tool: ask-user
  arguments:
    question: "What would you like to do?"
    options:
      - value: "build"
        description: "Build the project"
      - value: "test"
        description: "Run tests"
      - value: "deploy"
        description: "Deploy to staging"
  output: var(action)
  next: route-action

route-action:
  tool: switch
  arguments:
    value: "{{ action }}"
  goto:
    build: do-build
    test: do-test
    deploy: do-deploy
    _: unknown-action

INPUT MODES

Single-line Mode (default)

Standard text input with Enter to submit.

Multi-line Mode

Allows multiple lines of input. Submit with two consecutive Enter presses or platform-specific end-of-input.

Selection Mode

Presents options in an interactive menu. Arrow keys to navigate, Enter to select.

RESTRICTIONS

Cannot be used in parallel blocks
Requires interactive terminal (stdin must be a TTY)
Will fail in CI/CD pipelines without terminal