Skip to content

prompt Tools

🛠️ Tools · ⬅ Top

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_binBuild is a module for bashPrompt which sets the Zesk Build home depending on your current directory
  • bashPromptModule_ApplicationPath is a module for bashPrompt which displays the current application/path as a badge in iTerm
  • consoleDefaultTitle can be used as a module to set the current title

Examples:

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

Functions

bashPrompt

Bash prompt creates the PS1 prompt with the following extra

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 - Executable. Optional. Module to enable or disable.
  • --remove module - 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 - Optional. Flag. 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 - Callable. Command is run prior to displaying the prompt, receives exit status from prior command

bashPromptColorScheme

Color schemes for prompts

Usage

bashPromptColorScheme

Color schemes for prompts Options are: - forest - light (default) - dark

Arguments

  • none

Return codes

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

bashPromptColorsFormat

Given a list of color names, generate the color codes

Usage

bashPromptColorsFormat text

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

Writes to standard output

Outputs color codes separated by colons.

Arguments

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

Return codes

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

Requires

decorations read inArray decorate listJoin

bashPromptMarkers

Set markers for terminal integration

Usage

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

Set markers for terminal integration Outputs the current marker settings, one per line (0, 1, or 2 lines will be output).

Arguments

  • --help - Optional. Flag. Display this help.
  • prefix - Optional. EmptyString. Prefix for all prompts.
  • suffix - Optional. EmptyString. 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

Arguments

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

Return codes

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

Bash Prompt Modules

To enable:

bashPrompt bashPromptModule_binBuild bashPromptModule_ApplicationPath

bashPromptModule_BuildProject

Check which bin/build we are running and keep local to

Usage

bashPromptModule_BuildProject

Check which bin/build we are running and keep local to current project. Activates when we switch between projects.

  • Re-sources bin/build so versions do not conflict.
  • Runs hook project-deactivate in the old project (using that bin/build library)
  • Runs the project-activate hook in the new project
  • Displays the change in Zesk Build version

Run-Hook: project-activate Run-Hook: project-deactivate

Arguments

  • none

Return codes

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

bashPromptModule_ApplicationPath

Show current application and path as a badge in iTerm2

Usage

bashPromptModule_ApplicationPath

Show current application and path as a badge in iTerm2

Arguments

  • none

Examples

bashPrompt bashPromptModule_ApplicationPath

Return codes

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

bashPromptModule_dotFilesWatcher

Watches your HOME directory for . files which are added

Usage

bashPromptModule_dotFilesWatcher

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

Arguments

  • none

Examples

bashPrompt bashPromptModule_dotFilesWatcher

Return codes

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

Requires

sort buildEnvironmentGetDirectory touch returnEnvironment read basename inArray decorate printf confirmYesNo statusMessage grep rm

bashPromptModule_TermColors

Sets the console colors based on the project you are

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 BUILD_COLORS_MODE based on background color Sets decorateStyle for valid styles

Support for iTerm2 is built-in and automatic

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

Requires

buildHome statusMessage buildEnvironmentGetDirectory directoryRequire cachedShaPipe decorate buildDebugEnabled iTerm2SetColors consoleConfigureColorMode

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.

Arguments

  • --help - Optional. Flag. 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

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.

Arguments

  • --source source - Required. File. Source file to source upon change.
  • --name name - Optional. String. The name to call this when changes occur.
  • --path path - Required. Directory. OneOrMore. A directory to scan for changes in .sh files
  • --file file - Required. File. 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 - Optional. Flag. 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

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 ] [ --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. (2025-12-22 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

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.
  • --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 - Optional. Flag. Display this help.

Return codes

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