# Overview
- [📦 crates.io](https://crates.io/crates/eliprompt)
- [📖 Documentation](https://docs.rs/eliprompt)
- [⚖ 0BSD license](https://spdx.org/licenses/0BSD.html)
CLI to generate a shell prompt.
# Font
The default prompt configuration uses symbols from [Nerd Fonts](https://www.nerdfonts.com/) and
expects one of them to be installed.
# Shell support
Only zsh is supported. Please open an issue if support for another shell is desired.
# Installation
```sh
cargo install eliprompt
```
Make sure `eliprompt` is in your `PATH` and add the following to `.zshrc`:
```sh
eval "$(eliprompt install --shell zsh)"
```
# Configuration
The prompt is made of blocks. Each block contains the text to display as well as the style
(foreground and background colors).
The configuration is stored in `~/.config/eliprompt/config.json`. It consists of a JSON object
of type [`Config`](#config-type). `Config` and the other JSON types involved are detailed below.
## `BlockProducer` type
JSON object with a single field named after its type among:
- [`Elapsed`](#elapsed-type)
- [`ExitCode`](#exitcode-type)
- [`GitHead`](#githead-type)
- [`GitPath`](#gitpath-type)
- [`Hostname`](#hostname-type)
- [`WorkingDirectory`](#workingdirectory-type)
- [`Username`](#username-type)
- [`Newline`](#newline-type)
- [`Space`](#space-type)
- [`Text`](#text-type)
- [`ExitStatusSymbol`](#exitstatussymbol-type)
- [`Or`](#or-type)
- [`Sequence`](#sequence-type)
- [`Separated`](#separated-type)
- [`Styled`](#styled-type)
## `Color` type
String with a CSS color name (e.g. `"red"`) or a CSS sRGB color (e.g. `"#ff1000"`).
## `Config` type
Root configuration object. JSON object with the following fields:
- `prompt` [optional]:
- Type: [`BlockProducer`](#blockproducer-type)
- The prompt definition.
- `alternative_prompt` [optional]:
- Type: [`BlockProducer`](#blockproducer-type) or `null`
- Alternative prompt definition to use when `$TERM` is `linux` or the environment variable
`ELIPROMPT_ALTERNATIVE_PROMPT` is defined.
- `timeout` [optional]:
- Type: [`Duration`](#duration-type)
- Maximum time allocated to build the prompt. If it takes longer, a default prompt will be shown.
## `Duration` type
String containing a duration with unit, e.g. `"3s"` for 3 seconds.
## `Elapsed` type
Shows the duration of the previous command. JSON object with the following fields:
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the duration.
- `threshold` [optional]:
- Type: [`Duration`](#duration-type)
- The duration of a command is displayed if and only if it took longer than the threshold.
## `ExitCode` type
Shows the exit code of the previous command if it was not zero. JSON object with the following
fields:
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the exit code.
## `ExitStatusSymbol` type
- `style` [optional]:
- Type: [`Style`](#style-type)
- Style to use when the exit status is zero.
- `error_style` [optional]:
- Type: [`Style`](#style-type)
- Style to use when the exit status is not zero.
- `contents`:
- Type: `String`
## `GitHead` type
Shows the current git branch. JSON object with the following fields:
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the git branch.
## `GitPath` type
If the current working directory is in a git repository, it is shown relative to the root of the
repository. JSON object with the following fields:
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the path.
## `Hostname` type
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the hostname.
## `Newline` type
Adds a newline character.
## `Or` type
List of [`BlockProducer`](#blockproducer-type) items. Returns blocks from the first producer that
produces at least one block.
## `Separated` type
- `separator_style` [optional]:
- Type: [`Style`](#style-type)
- Style to use for the separator.
- `separator` [optional]:
- Type: `String`
- Separator to insert between groups of blocks generated by the producers.
- `producers`:
- Type: List of [`BlockProducer`](#blockproducer-type) items
## `Sequence` type
List of [`BlockProducer`](#blockproducer-type) items. Returns blocks from all producers.
## `Space` type
Adds a space character.
## `Style` type
JSON object with the following fields:
- `foreground` [optional]:
- Type: [`Color`](#color-type) or `null`
- `background` [optional]:
- Type: [`Color`](#color-type) or `null`
## `Styled` type
- `style` [optional]:
- Type: [`Style`](#style-type)
- Default style for items that do not specify their foreground or background color.
- `producer`:
- Type: [`BlockProducer`](#blockproducer-type)
- Generator whose blocks the default style is applied to.
## `Text` type
- `style` [optional]:
- Type: [`Style`](#style-type)
- `contents`:
- Type: `String`
## `Username` type
- `style` [optional]:
- Type: [`Style`](#style-type)
- `prefix` [optional]:
- Type: `String`
- Text to display before the username.
## `WorkingDirectory` type
Shows the current working directory. JSON object with the following fields:
- `style` [optional]:
- Type: [`Style`](#style-type)
- `home_as_tilde` [optional]:
- Type: `bool`
- Indicates if the home directory should be displayed as a tilde.
- `prefix` [optional]:
- Type: `String`
- Text to display before the working directory.
## Example
```json
{
"prompt": {
"Styled": {
"style": {
"foreground": "teal",
"background": "black"
},
"producer": {
"Sequence": [
{
"Separated": {
"separator_style": {},
"separator": " | ",
"producers": [
{
"Separated": {
"separator_style": {},
"separator": "@",
"producers": [
{
"Username": {
"style": {},
"prefix": ""
}
},
{
"Hostname": {
"style": {},
"prefix": ""
}
}
]
}
},
{
"Or": [
{
"GitPath": {
"style": {},
"prefix": ""
}
},
{
"WorkingDirectory": {
"style": {},
"home_as_tilde": true,
"prefix": ""
}
}
]
},
{
"GitHead": {
"style": {},
"prefix": ""
}
},
{
"Elapsed": {
"style": {},
"prefix": "祥",
"threshold": "2s"
}
},
{
"ExitCode": {
"style": {
"foreground": "crimson"
},
"prefix": ""
}
}
]
}
},
{
"Newline": null
},
{
"ExitStatusSymbol": {
"style": {
"foreground": "dodgerblue"
},
"error_style": {
"foreground": "crimson"
},
"contents": "→"
}
},
{
"Space": null
}
]
}
}
},
"alternative_prompt": {
"Styled": {
"style": {
"foreground": "teal"
},
"producer": {
"Sequence": [
{
"Separated": {
"separator_style": {},
"separator": " | ",
"producers": [
{
"Separated": {
"separator_style": {},
"separator": "@",
"producers": [
{
"Username": {
"style": {},
"prefix": ""
}
},
{
"Hostname": {
"style": {},
"prefix": ""
}
}
]
}
},
{
"WorkingDirectory": {
"style": {},
"home_as_tilde": true,
"prefix": ""
}
},
{
"Elapsed": {
"style": {},
"prefix": "",
"threshold": "2s"
}
},
{
"ExitCode": {
"style": {
"foreground": "crimson"
},
"prefix": ""
}
}
]
}
},
{
"Newline": null
},
{
"ExitStatusSymbol": {
"style": {
"foreground": "dodgerblue"
},
"error_style": {
"foreground": "crimson"
},
"contents": "→"
}
},
{
"Space": null
}
]
}
}
},
"timeout": "1s"
}
```
# Contribute
All contributions shall be licensed under the [0BSD license](https://spdx.org/licenses/0BSD.html).
# Related projects
[starship](https://github.com/starship/starship) provides more blocks and supports more shells.