Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gnmyt/Nexterm/llms.txt

Use this file to discover all available pages before exploring further.

Nexterm provides a set of special directives that turn plain shell scripts into interactive, user-guided workflows. Prefixed with @NEXTERM:, these annotations let you collect user input, display real-time status messages, track progress, and present structured results — all without modifying the server-side execution environment.

​
Overview

Directives are embedded directly in your script file as lines beginning with @NEXTERM:. When Nexterm runs the script, it intercepts these lines and renders the corresponding UI element before continuing execution. You can use directives to:
  • Break a complex script into labeled steps
  • Collect text input or offer a choice from a fixed list
  • Require explicit confirmation before a destructive operation
  • Display info, warning, success, and error messages in real time
  • Show a progress percentage during a long-running operation
  • Present a key-value summary when the script finishes
Directives are interpreted by Nexterm at execution time. They are not executed as shell commands on the server, so they have no effect if you run the same script outside of Nexterm.

​
Available directives

Marks a logical step in your script and displays it in the UI. Use steps to break a complex script into named phases so users can follow along.Syntax:
@NEXTERM:STEP "Step description"
Example:
@NEXTERM:STEP "Installing dependencies"
npm install

@NEXTERM:STEP "Building the application"
npm run build

@NEXTERM:STEP "Running tests"
npm test
Prompts the user to enter a value. An optional second parameter sets the default if the user submits the form without typing anything.Syntax:
@NEXTERM:INPUT "Prompt message" "default value"
Parameters:
  • First: the prompt message displayed to the user
  • Second (optional): the default value used when no input is provided
Example:
@NEXTERM:INPUT "Enter the database host" "localhost"
@NEXTERM:INPUT "Enter the database port" "5432"
@NEXTERM:INPUT "Enter the API key" ""
Always provide a sensible default for common values like hostnames and ports. This reduces the number of fields users must fill in for typical runs.
Presents the user with a set of predefined options and captures their selection. Use this instead of free-text input whenever valid values are known in advance.Syntax:
@NEXTERM:SELECT "Prompt message" "Option 1" "Option 2" "Option 3"
Parameters:
  • First: the prompt message
  • Remaining: one argument per option
Example:
@NEXTERM:SELECT "Select deployment environment" "Development" "Staging" "Production"
@NEXTERM:SELECT "Choose backup type" "Full" "Incremental" "Differential"
@NEXTERM:SELECT "Select database version" "PostgreSQL 12" "PostgreSQL 13" "PostgreSQL 14"
Pauses execution and displays a confirmation prompt. The script does not continue until the user confirms. Use this before any operation that is destructive or irreversible.Syntax:
@NEXTERM:CONFIRM "Confirmation message"
Example:
@NEXTERM:STEP "Preparing to delete database"
@NEXTERM:CONFIRM "Are you sure you want to delete the entire database? This cannot be undone."
rm -rf /var/lib/postgresql/data
Shows an informational notice without blocking execution. Use it to explain what the script is about to do, especially before a long-running command.Syntax:
@NEXTERM:INFO "Information message"
Example:
@NEXTERM:INFO "Docker is not installed. Installing Docker now..."
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

@NEXTERM:INFO "Configuration will be applied after the service restarts."
systemctl restart myservice
Displays a success message to confirm that a task or phase finished successfully.Syntax:
@NEXTERM:SUCCESS "Success message"
Example:
@NEXTERM:STEP "Deploying application"
docker pull myapp:latest
docker run -d myapp:latest
@NEXTERM:SUCCESS "Application deployed successfully!"

@NEXTERM:STEP "Running health checks"
curl http://localhost:8080/health
@NEXTERM:SUCCESS "All health checks passed!"
Alerts the user to a potential issue without stopping execution. Use it for situations that require awareness but not a hard stop.Syntax:
@NEXTERM:WARN "Warning message"
Example:
@NEXTERM:STEP "Updating production configuration"
@NEXTERM:WARN "You are modifying production configuration. Ensure you have a backup."
cp config.prod.yml config.prod.yml.backup
sed -i 's/old_value/new_value/g' config.prod.yml

@NEXTERM:WARN "This operation requires manual verification in the admin panel."
Displays an error message. This is informational — it does not stop execution on its own. Pair it with exit 1 to abort the script when a critical prerequisite is not met.Syntax:
@NEXTERM:ERROR "Error message"
Example:
@NEXTERM:STEP "Verifying prerequisites"
if ! command -v docker &> /dev/null; then
    @NEXTERM:ERROR "Docker is not installed. Please install Docker before proceeding."
    exit 1
fi
@NEXTERM:SUCCESS "All prerequisites verified"

@NEXTERM:STEP "Connecting to database"
if ! psql -h localhost -U user -d mydb -c "SELECT 1" &> /dev/null; then
    @NEXTERM:ERROR "Failed to connect to database. Check your connection parameters."
    exit 1
fi
Updates a visual progress indicator with a percentage value between 0 and 100. Call it repeatedly inside a loop to show activity during a long-running operation.Syntax:
@NEXTERM:PROGRESS 50
Parameters:
  • A single integer from 0 to 100 representing the completion percentage
Example:
@NEXTERM:STEP "Processing large file"
total_lines=$(wc -l < input.txt)

@NEXTERM:PROGRESS 0
processed=0
while IFS= read -r line; do
    process_line "$line"
    ((processed++))
    percentage=$((processed * 100 / total_lines))
    @NEXTERM:PROGRESS "$percentage"
done < input.txt

@NEXTERM:PROGRESS 100
@NEXTERM:SUCCESS "File processed successfully"
Renders a labeled key-value table at the end of a script. Use it to present final statistics, configuration values, or completion details in a readable format.Syntax:
@NEXTERM:SUMMARY "Title" "Key 1" "Value 1" "Key 2" "Value 2"
Parameters:
  • First: the summary title
  • Remaining: alternating key-value pairs
Example:
@NEXTERM:STEP "Gathering server statistics"
uptime_value=$(uptime)
memory_value=$(free -h | grep Mem | awk '{print $2}')
disk_value=$(df -h / | awk 'NR==2 {print $2}')
cpu_value=$(nproc)

@NEXTERM:SUMMARY "Server Information" \
    "Uptime" "$uptime_value" \
    "Total Memory" "$memory_value" \
    "Total Disk" "$disk_value" \
    "CPU Cores" "$cpu_value"

​
Complete example

The script below combines several directives to walk a user through a deployment workflow:
deploy.sh
# @name: Deploy application
# @description: Pull the latest Docker image and run a health check
# @os: Ubuntu, Debian

@NEXTERM:STEP "Collecting deployment parameters"
@NEXTERM:SELECT "Select environment" "Staging" "Production"
@NEXTERM:INPUT "Docker image tag" "latest"

@NEXTERM:STEP "Verifying prerequisites"
if ! command -v docker &> /dev/null; then
    @NEXTERM:ERROR "Docker is not installed."
    exit 1
fi
@NEXTERM:SUCCESS "Docker is available"

@NEXTERM:STEP "Pulling image"
@NEXTERM:PROGRESS 0
docker pull myapp:latest
@NEXTERM:PROGRESS 50

@NEXTERM:CONFIRM "Deploy to production now?"
docker run -d --name myapp myapp:latest
@NEXTERM:PROGRESS 100

@NEXTERM:STEP "Health check"
sleep 5
curl -sf http://localhost:8080/health
@NEXTERM:SUCCESS "Deployment complete"

@NEXTERM:SUMMARY "Deployment Results" \
    "Image" "myapp:latest" \
    "Container" "myapp" \
    "Health endpoint" "http://localhost:8080/health"

​
Best practices

  1. Use @NEXTERM:STEP for every distinct phase — it gives users a clear map of where the script is in its execution.
  2. Provide defaults in @NEXTERM:INPUT — reduce friction for the most common case while still allowing customization.
  3. Prefer @NEXTERM:SELECT over free-text input — restricting choices to known-good values prevents typos and invalid configurations.
  4. Guard destructive operations with @NEXTERM:CONFIRM — deletions, production deployments, and data migrations should always require an explicit acknowledgment.
  5. Use @NEXTERM:ERROR with exit 1 — display an actionable message and then abort when a prerequisite check fails.
  6. Update @NEXTERM:PROGRESS frequently — call it at each meaningful checkpoint so users know the script has not stalled.
  7. End with @NEXTERM:SUMMARY — a final summary of key outcomes helps users verify that the script completed as expected.

Scripts and snippets

Learn how to create, format, and organize scripts and snippets in Nexterm.

Build docs developers (and LLMs) love

Get started for freeTalk to us