prompt Tools

---

The prompt supports a few things:

• user@host ~/path prefix
• Exit status of previous command is displayed
• Manage a queue of functions to run on each shell command

Tools to work with the shell prompt PS1

• bashPromptModule_BuildProject is a module for bashPrompt which deactivates and activates your Zesk Build project depending on your current directory
• bashPromptModule_ApplicationPath is a module for bashPrompt which displays the current application/path as a badge in iTerm
• bashPromptModule_dotFilesWatcher is a module for bashPrompt which monitors your home directory for files which start with . and lets you know when new ones have been added, and manages an approved list of files allowed.
• consoleDefaultTitle can be used as a module to set the current title

Examples:

bashPrompt bashPromptModule_BuildProject consoleDefaultTitle
bashPrompt --colors "$(bashPromptColorScheme forest)"

Prompt Functions

bashPrompt

Bash prompt toolkit

Usage

bashPrompt [ module ] [ --remove module ] [ --reset ] [ --list ] [ --first ] [ --last ] [ --order order ] [ --format promptFormat ] [ --success successText ] [ --failure failureText ] [ --label promptLabel ] [ --colors colorsText ] [ --skip-prompt ] [ --help ]

Bash prompt creates the PS1 prompt with the following extra features:

• Easy colorization
• Easy customization
• Return code of prior command dynamically displayed in following prompt
• Easily extend your bash prompt with modules

PROMPT MODULES

Modules are any binary or executable to run each prompt, and can be added, removed or managed here.

COLORS

The --colors are currently a :-separated list of color names (not escape codes), in order:

1. Success color (Array index 0)
2. Failure color (Array index 1)
3. User color (Array index 2)
4. Host color (Array index 3)
5. Directory color (Array index 4)

Arguments

• module - Callable. Optional. Module to enable or disable.
• --remove module - Callable. Optional. Remove the module specified (should match exactly)
• --reset - Flag. Optional. Remove all prompt modules.
• --list - Flag. Optional. List the current modules. Modules are also added or removed, otherwise no changes are made.
• --first - Flag. Optional. Add all subsequent modules first to the list.
• --last - Flag. Optional. Add all subsequent modules last to the list.
• --order order - UnsignedInteger. Optional. Set the order index for this prompt. 0 is first, higher numbers are later.
• --format promptFormat - String. Optional. Display this label on each prompt.
• --success successText - EmptyString. Optional. Text to display in the prompt when the previous command succeeded.
• --failure failureText - EmptyString. Optional. Text to display in the prompt when the previous command failed.
• --label promptLabel - String. Optional. The prompt format string. See PROMPT FORMATTING below
• --colors colorsText - String. Optional. Set the prompt colors. See COLORS below.
• --skip-prompt - Flag. Optional. Do not modify the prompt.
• --help - Flag. Optional. Display this help.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

• bashPrompt - Debug prompt command execution

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

Environment

• PROMPT_COMMAND Prompt function – Callable. Command is run before displaying the prompt, receives exit status

bashPromptColorScheme

Color scheme values for prompts

Usage

bashPromptColorScheme [ colorScheme ] [ --help ]

Color schemes for prompts. Use this as an argument to bashPrompt --colors.

Options are:

• forest
• light (default)
• dark

Location: bin/build/tools/prompt.sh

Arguments

• colorScheme - String. Optional. Color scheme to choose: light, dark, forest
• --help - Flag. Optional. Display this help.

Examples

bashPrompt --colors "$(bashPromptColorScheme dark)"

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

bashPromptColorsFormat

Convert colors to escape codes

Usage

bashPromptColorsFormat text

Given a list of color names, generate the color codes in a colon separated list.

Location: bin/build/tools/prompt.sh

Arguments

• text - String. Required. List of color names in a colon separated list.

Writes to standard output

Outputs color codes separated by colons.

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

Requires

• decorations - Output a list of build-in decoration styles, one per line (source)
• read
• inArray - Check if an element exists in an array (source)
• decorate - decorate text using colors and styles (source)
• listJoin - Output a list of items joined by a character (source)

bashPromptMarkers

Set markers for terminal integration

Usage

bashPromptMarkers [ --help ] [ prefix ] [ suffix ]

Set markers for terminal integration; these markers are terminal commands which mark the start and finish of the bash prompt for easier text selection by some terminals. Outputs the current marker settings, one per line (0, 1, or 2 lines will be output).

Location: bin/build/tools/prompt.sh

Arguments

• --help - Flag. Optional. Display this help.
• prefix - EmptyString. Optional. Prefix for all prompts.
• suffix - EmptyString. Optional. Suffix for all prompts.

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

bashUserInput

Prompt the user properly honoring any attached console.

Usage

bashUserInput [ --help ] [ ... ]

Prompt the user properly honoring any attached console.

Arguments are the same as read, except:

-r is implied and does not need to be specified

Location: bin/build/tools/prompt.sh

Arguments

• --help - Flag. Optional. Display this help.
• ... - Arguments. Optional. Identical arguments to read (but includes -r)

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

See Also

• read

bashPrompt Modules

• {SEE:bashPromptModule_BuildProject}
• {SEE:bashPromptModule_ApplicationPath}
• bashPromptModule_dotFilesWatcher - Monitor home directory for new `.` files (source)
• bashPromptModule_TermColors - Terminal colors to match projects (source)

To enable:

bashPrompt bashPromptModule_BuildProject bashPromptModule_ApplicationPath

{bashPromptModule_BuildProject}

{bashPromptModule_ApplicationPath}

bashPromptModule_dotFilesWatcher

Monitor home directory for new . files

Usage

bashPromptModule_dotFilesWatcher

Watches your HOME directory for . files which are added and unknown to you.

Location: bin/build/tools/prompt-modules.sh

Arguments

• none

Examples

bashPrompt bashPromptModule_dotFilesWatcher

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

Requires

• sort
• buildEnvironmentGetDirectory - Load and print one or more environment settings which represents (source)
• touch
• returnEnvironment - Return `environment` error code. Outputs `message ...` to `stderr`. (source)
• read
• basename
• inArray - Check if an element exists in an array (source)
• decorate - decorate text using colors and styles (source)
• printf
• confirmYesNo - Read user input and return success on yes (source)
• statusMessage - Output a status message and display correctly on consoles with animation and in log files (source)
• grep
• rm

bashPromptModule_TermColors

Terminal colors to match projects

Usage

bashPromptModule_TermColors

Sets the console colors based on the project you are currently in. Define your color configuration file (values of bg=FFF etc. one per line, comments allowed)

Will fill in missing bright or non-bright colors which are unspecified. (blue implies br_blue and so on)

Sets decorateStyle for valid styles

Support for iTerm2 is built-in and automatic

Location: bin/build/tools/prompt.sh

Arguments

• none

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

• term-colors - When bashPromptModule_TermColors is enabled, will show colors and how they are applied

Examples

bashPrompt --order 80 bashPromptModule_TermColors

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

Environment

• BUILD_TERM_COLORS_STATE Terminal Color State – String. State to store state of current terminal color state

Requires

• buildHome - Prints the build home directory (usually same as the application (source)
• statusMessage - Output a status message and display correctly on consoles with animation and in log files (source)
• buildEnvironmentGetDirectory - Load and print one or more environment settings which represents (source)
• directoryRequire - Given a list of directories, ensure they exist and create (source)
• textSHA - SHA1 checksum of standard input (source)
• --cachedecorate
• buildDebugEnabled - Is build debugging enabled? (source)
• iTerm2SetColors - Set terminal colors (source)
• consoleConfigureColorMode - Print the suggested color mode for the current environment (source)

See Also

• consoleConfigureColorMode - Print the suggested color mode for the current environment (source)

dotFilesWatcher Tools

Example during setup:

dotFilesApproved bash > "$(dotFilesApprovedFile)"

And then in your bash prompt:

bashPrompt bashPromptModule_dotFilesWatcher

Any new dot files which appear will then show a warning in your console.

dotFilesApprovedFile

The dot files approved file. Add files to this to

Usage

dotFilesApprovedFile [ --help ]

The dot files approved file. Add files to this to approve.

Location: bin/build/tools/prompt-modules.sh

Arguments

• --help - Flag. Optional. Display this help.

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

dotFilesApproved

Lists of dot files which can be added to the

Usage

dotFilesApproved [ listType ]

Lists of dot files which can be added to the dotFilesApprovedFile If none specified, returns bash list. Special value all returns all values

Location: bin/build/tools/prompt-modules.sh

Arguments

• listType - String. Optional. One of all, bash, git, darwin, or mysql

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

reloadChanges Tools

reloadChanges

Watch or more directories for changes in a file extension

Usage

reloadChanges --source source [ --name name ] --path path --file file [ --stop ] [ --show ] [ source ] [ path|file ... ] [ --help ]

Watch or more directories for changes in a file extension and reload a source file if any changes occur.

Location: bin/build/tools/prompt-modules.sh

Arguments

• --source source - File. Required. Source file to source upon change.
• --name name - String. Optional. The name to call this when changes occur.
• --path path - Directory. Required. OneOrMore. A directory to scan for changes in .sh files
• --file file - File. Required. OneOrMore. A file to watch.å
• --stop - Flag. Optional. Stop watching changes and remove all watches.
• --show - Flag. Optional. Show watched settings and exit.
• source - File. Optional. If supplied directly on the command line, sets the source.
• path|- file ... - DirectoryOrFile. Optional. If source supplied, then any other command line argument is treated as a path to scan for changes.
• --help - Flag. Optional. Display this help.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

• reloadChanges - prompt module will show debugging information
• reloadChangesProfile - prompt module will show profiling information

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

Background Process Tools

backgroundProcess

Background process manager for shell (UNSTABLE)

Usage

backgroundProcess [ --verbose ] [ --report ] [ --summary ] [ --monitor ] [ --watch ] [ --verbose-toggle ] [ --terminate ] [ --go ] [ --new-only ] [ --stop stopSeconds ] [ --wait waitSeconds ] [ --frequency checkSeconds ] condition ... -- command ... [ --help ]

UNSTABLE: Seems this does not handle long processes well which do not quit quickly. Need to improve testing. Use at your own risk. (2026-01-12 KMD)

Run a single process in the background continuously until a condition is met.

condition and command required when an action flag is not specified.

Action flags:

--go --report --monitor --verbose-toggle --stop-all --summary

This can be used to run processes on your code in the background.

The condition should output any form of output which, when it changes (or exits non-zero), will require the command to be run. As long as the condition remains the same between calls, command is not run.

Once command is run the process is monitored; and every stopSeconds seconds condition is run again - if condition changes between the starting value and the new value then the command is terminated. The manager waits waitSeconds and then runs command again. (Capturing condition at the start.)

If condition exits zero – then it is simply run every checkSeconds seconds to see if command needs to be run again.

This allows you to have background processes which, while you edit your code, for example, will pause momentarily while you edit and not use up all of your available CPU.

To see status, try:

backgroundProcess --summary
backgroundProcess --report
backgroundProcess --monitor
backgroundProcess --watch

Location: bin/build/tools/prompt-modules.sh

Arguments

• --verbose - Flag. Optional. Be verbose.
• --report - Flag. Optional. Show a long report of all processes.
• --summary - Flag. Optional. Show a summary of all processes.
• --monitor - Flag. Optional. Interactively show report and refresh.
• --watch - Flag. Optional. Repeat showing summary.
• --verbose-toggle - Flag. Optional. Toggle the global verbose reporting.
• --terminate - Flag. Optional. Terminate all processes and delete all background process records.
• --go - Flag. Optional. Check all process states and update them.
• --new-only - Flag. Optional. Output a message for new processes only.
• --stop stopSeconds - PositiveInteger. Optional. Check every stop seconds after starting to see if should be stopped.
• --wait waitSeconds - PositiveInteger. Optional. After stopping, wait this many seconds before trying again.
• --frequency checkSeconds - PositiveInteger. Optional. Check condition at this frequency.
• condition ... - Callable. Required. Condition to test. Output of this is compared to see if we should stop process and restart it.
• -- - Delimiter. Required. Separates command.
• command ... - Callable. Required. Function to run in the background.
• --help - Flag. Optional. Display this help.

Return codes

• 0 - Success
• 1 - Environment error
• 2 - Argument error

---

🛠️ Tools · ⬅ Top