{"id":24344172,"url":"https://github.com/brandonweiss/promptconfig","last_synced_at":"2025-06-18T01:41:00.098Z","repository":{"id":33201108,"uuid":"153186483","full_name":"brandonweiss/promptconfig","owner":"brandonweiss","description":"🖥 Craft a custom terminal prompt with JSON.","archived":false,"fork":false,"pushed_at":"2023-01-04T21:57:06.000Z","size":1312,"stargazers_count":35,"open_issues_count":13,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-04T11:35:05.895Z","etag":null,"topics":["bash","prompt","shell","terminal","x"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brandonweiss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-15T21:52:47.000Z","updated_at":"2023-04-27T15:50:00.000Z","dependencies_parsed_at":"2023-01-14T23:53:24.232Z","dependency_job_id":null,"html_url":"https://github.com/brandonweiss/promptconfig","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/brandonweiss/promptconfig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonweiss%2Fpromptconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonweiss%2Fpromptconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonweiss%2Fpromptconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonweiss%2Fpromptconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brandonweiss","download_url":"https://codeload.github.com/brandonweiss/promptconfig/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brandonweiss%2Fpromptconfig/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260470349,"owners_count":23014207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","prompt","shell","terminal","x"],"created_at":"2025-01-18T09:22:44.761Z","updated_at":"2025-06-18T01:40:55.081Z","avatar_url":"https://github.com/brandonweiss.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\t\u003cbr\u003e\n\t\u003cimg src=\"media/logomark.svg?sanitize=true\" width=\"300px\" alt=\"PromptConfig\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n  PromptConfig\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\u003c/h1\u003e\n\n[![](https://badgen.net/travis/brandonweiss/promptconfig?icon=travis)](https://www.travis-ci.com/brandonweiss/promptconfig)\n[![](https://badgen.net/npm/v/promptconfig?icon=npm)](https://www.npmjs.com/package/promptconfig)\n![](https://badgen.net/npm/node/promptconfig)\n[![](https://badgen.net/david/dep/brandonweiss/promptconfig)](https://david-dm.org/brandonweiss/promptconfig)\n![](https://badgen.net/badge/documentation/lit/purple)\n\n### What?\n\nCraft a custom terminal prompt with JSON.\n\nYou describe your prompt expressively in JSON and then it gets compiled to Bash. A very simple prompt might look like this:\n\n```json\n{\n  \"prompt\": [\"character\", \"space\"],\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": \"magenta\"\n    }\n  ]\n}\n```\n\nAnd it will generate Bash that looks like this:\n\n```bash\nfunction _promptconfig_prompt() {\n  local prompt=''\n  prompt+='\\[\\e[38;5;5m\\]'\n  prompt+='❯'\n  prompt+='\\[\\e[0m\\]'\n  prompt+=' '\n  PS1=$prompt\n}\n\nPROMPT_COMMAND=\"_promptconfig_prompt; $PROMPT_COMMAND\"\n```\n\n### Why?\n\nBash is hard. It’s an arcane language and environment with a steep learning curve. Most programmers wind up using it on a very superficial level, figuring out just enough to get done what they need to do.\n\nUnfortunately, customizing your prompt correctly requires a disproportionately high understanding of how Bash and the terminal work relative to what you’re trying to actually do. The internet is filled with recommendations that will break your prompt in subtle ways that aren’t immediately obvious and later you might not understand are caused by your custom prompt. I’m speaking from personal experience. 😭\n\nIt shouldn’t be that complicated and hopefully now it isn’t.\n\n## Installation\n\nInstall it globally using npm:\n\n```shell\n❯ npm install --global promptconfig\n```\n\n## Usage\n\nOnce you’ve configured your prompt in JSON, run `promptconfig`, passing in the path to the JSON file.\n\n```shell\n❯ promptconfig \u003cJSON configuration file\u003e\n```\n\nYou probably want to redirect the output to a Bash file, e.g.\n\n```shell\n❯ promptconfig prompt.json \u003e ~/prompt.bash\n```\n\nThen put `source prompt.bash` in your `~/.bashrc` or `~/.bash_profile`, whichever you have/use. Open a new Terminal window and you should see your new prompt!\n\n### Configuration\n\nThere are two parts to the configuration: `prompt` and `components`. `prompt` defines the structure/layout of your prompt using both built-in and custom components. `components` defines the custom components you use in `prompt`.\n\n### Prompt\n\nThe simplest form of the `prompt` configuration is just an array of component keys.\n\n```json\n{\n  \"prompt\": [\"character\", \"space\"]\n}\n```\n\nThe array represents one line of your prompt. If you want your prompt to appear on multiple lines, you can use the built-in `newline` component.\n\n```json\n{\n  \"prompt\": [\"working_directory\", \"newline\", \"character\", \"space\"]\n}\n```\n\n`prompt` can also be an array of arrays.\n\n```json\n{\n  \"prompt\": [\n    [\"working_directory\"],\n    [\"character\", \"space\"]\n  ]\n}\n```\n\nEach array represents a line in the prompt. For multi-line prompts it’s a bit clearer than using the `newline` component.\n\nIf you want a blank line in your prompt to visually break up commands, you can use an empty array.\n\n```json\n{\n  \"prompt\": [\n    [],\n    [\"character\", \"space\"]\n  ]\n}\n```\n\n### Components\n\nThere are two built-in components that are available as a convenience: `newline` and `space.` Any other component you want you’ll need to create.\n\nEvery component must have a `key` and `value`, `function`, or `command`. Optionally, some components can have `conditions` and `color`.\n\n`key` is a unique string used to reference the component in the `prompt` configuration and control its position in the prompt.\n\n`value`, `function`, and `command` are types that control how the component behaves.\n\n#### Value\n\nThe simplest type is `value`. You can use it to output plain text.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n    }\n  ]\n}\n```\n\n#### Command\n\nA more complex type is `command`. You can use it to execute arbitrary shell commands.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"username\",\n      \"command\": \"whoami\",\n    }\n  ]\n}\n```\n\n**NB**: When writing commands with backslash escapes, remember to use _two_ backslashes, e.g. `\"\\\\n\"`. The first backslash is escaping the second backslash in the JSON and will not show up in the final Bash output. The second backslash is for Bash and will show up in the final Bash output.\n\n#### Function\n\nThe last type is `function`. It allows you to use built-in, predefined commands.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"working_directory\",\n      \"function\": \"working_directory\",\n    }\n  ]\n}\n```\n\nThe available functions are:\n\n* `working_directory`: Returns the current git branch name\n* `git_branch_name`: Returns the current git branch name\n* `git_behind_upstream`: Returns whether there are commits upstream waiting to be pulled\n* `git_ahead_of_upstream`: Returns whether there are commits locally waiting to be pushed\n* `exit_status`: Returns whether the previously executed command was successful\n\nIf there is a command that you think is generic and widely-used enough to be included as a function, please open a pull request!\n\nYou’ll notice that some functions like `working_directory` return text, while others like `git_behind_upstream` indicate true or false. You can make use of the boolean functions with `conditions`.\n\n#### Conditions\n\nConditions allow you compare the return value of a command or function and return other plain text instead.\n\nIf the conditions are `true` and `false`, only `true`, or only `false`, then it’s assumed you want to check whether the command or function exited successfully or not.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"exit_status\",\n      \"function\": \"exit_status\",\n      \"conditions\": {\n        \"true\": \"✅\",\n        \"false\": \"❌\"\n      }\n    }\n  ]\n}\n```\n\nIf the conditions are anything else, it’s assumed you want to compare equality against what the command or function returned.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"username\",\n      \"command\": \"whoami\",\n      \"conditions\": {\n        \"brandon\": \"👨‍💻\",\n        \"root\": \"🔒\"\n      }\n    }\n  ]\n}\n```\n\n#### Color\n\nWhat would a prompt be without pretty colors? `color` can be an ANSI 16 color name or an ANSI 256 color code.\n\n##### ANSI 16 color name\n\nThe actual color values these names represent are typically controlled by settings in your Terminal app. Most Terminal apps have the concept of “themes” that allow you to change these values. It’s generally preferable to use ANSI 16 color names to color your prompt so that your Terminal uses colors consistently.\n\n1. `black`\n2. `red`\n3. `green`\n4. `yellow`\n5. `blue`\n6. `magenta`\n7. `cyan`\n8. `white`\n9. `bright_black`\n10. `bright_red`\n11. `bright_green`\n12. `bright_yellow`\n13. `bright_blue`\n14. `bright_magenta`\n15. `bright_cyan`\n16. `bright_white`\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": \"magenta\"\n    }\n  ]\n}\n```\n\n##### ANSI 256 color code\n\nIf you have a very specific color you want to use you can choose any [ANSI 256 color code][ANSI 256]—a number between 0 and 255.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": 124\n    }\n  ]\n}\n```\n\n##### Behavior\n\nDefining `color` like that is actually a shorthand. For example, this:\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": \"magenta\"\n    }\n  ]\n}\n```\n\nIs equivalent to this:\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": {\n        \"value\": \"magenta\",\n      }\n    }\n  ]\n}\n```\n\n`color` has behavior in the same way `components` have behavior. That means `color` can have a `value`, `command`, or `function`, and optionally `conditions`.\n\n```json\n{\n  \"components\": [\n    {\n      \"key\": \"character\",\n      \"value\": \"❯\",\n      \"color\": {\n        \"function\": \"exit_status\",\n        \"conditions\": {\n          \"true\": \"magenta\",\n          \"false\": \"red\"\n        }        \n      }\n    }\n  ]\n}\n```\n\nThis is an example of using the `exit_status` function to conditionally color the prompt character to “magenta” if the last command was successful or “red” if it was unsuccessful.\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub][github-promptconfig].\n\n## License\n\nThe package is available as open source under the terms of the [MIT License][MIT-license].\n\n[ANSI 256]: https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit\n[github-promptconfig]: https://github.com/brandonweiss/promptconfig\n[MIT-License]: http://opensource.org/licenses/MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonweiss%2Fpromptconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrandonweiss%2Fpromptconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrandonweiss%2Fpromptconfig/lists"}