{"slug": "show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready", "title": "Show your Neon branch in your terminal prompt (Starship) — copy-paste / agent-ready setup", "summary": "A developer created a Starship prompt segment that displays the current Neon branch linked to a directory. The segment uses the Neon CLI's `neon status --current-branch` command, which reads a local `.neon` file without making network requests. It is hidden when not in a Neon project, and the setup is provided as a copy-paste configuration for Starship.", "body_md": "Tweet: [https://x.com/thisistonydang/status/2071723089755603091](https://x.com/thisistonydang/status/2071723089755603091)\n\nA drop-in [Starship](https://starship.rs) segment that displays the **Neon branch** your\ncurrent directory is linked to, powered by the Neon CLI. It appears only inside directories\nlinked to a Neon project, and shows nothing everywhere else.\n\n```\n~/code/my-app  🌿 main  ❯\n```\n\nUsing a coding agent?Hand it this whole file by saying:\"Set up Starship with the Neon branch segment by following this gist:The steps below are ordered, idempotent (safe to re-run), and self-checking.[https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7]\"\n\n- Adds a\n`[custom.neon]`\n\nmodule to Starship that runs`neon status --current-branch`\n\n. - That command prints the branch pinned in the nearest\n`.neon`\n\nfile (walking up the directory tree) and makes**no network request**— it just reads a local file. - The segment is\n**hidden** when you're not in a Neon project (the command exits non-zero when no branch is pinned), so you never get a stray icon.\n\n**Node.js ≥ 22**—`node --version`\n\n**Neon CLI ≥ 2.28.0**— provides`neon status --current-branch`\n\n. Install/update:`npm install -g neonctl`\n\n(the installed commands are`neon`\n\nand`neonctl`\n\n).**Starship**—[https://starship.rs/guide/#-installation](https://starship.rs/guide/#-installation)** A linked Neon project**in the directory where you want the branch to show:`neon link`\n\nthen`neon checkout <branch>`\n\n(this writes a local`.neon`\n\nfile with the branch).\n\nRun these in order. Each step is safe to re-run.\n\n```\nnode --version       # expect v22+  (Neon CLI 2.28.0+ requires Node >= 22)\nneon --version       # expect 2.28.0+ ; if missing or older: npm install -g neonctl\nstarship --version   # if missing, install from https://starship.rs\n```\n\nAdd the matching line to your shell rc **if it isn't already there**:\n\n**zsh**— append to`~/.zshrc`\n\n:`eval \"$(starship init zsh)\"`\n\n**bash**— append to`~/.bashrc`\n\n:`eval \"$(starship init bash)\"`\n\n**fish**— append to`~/.config/fish/config.fish`\n\n:`starship init fish | source`\n\n```\nmkdir -p ~/.config && touch ~/.config/starship.toml\n```\n\nAppend this block to `~/.config/starship.toml`\n\n**only if a [custom.neon] table is not already\npresent** (don't create a duplicate\n\n`[custom.neon]`\n\n):\n\n```\n[custom.neon]\ndescription = \"Current Neon branch\"\ncommand = \"neon status --current-branch\"   # prints the branch pinned in .neon (no network)\nwhen = \"neon status --current-branch\"       # exits non-zero when no branch -> segment is hidden\nsymbol = \"🌿 \"\nstyle = \"bold green\"\nformat = \"[$symbol$output]($style) \"\n```\n\nIf your `starship.toml`\n\ndefines its own `format = \"...\"`\n\n, add `${custom.neon}`\n\nwherever you want\nthe branch to appear (e.g. right after `$git_branch`\n\n). If you have **no** custom `format`\n\n,\nStarship shows custom modules automatically — nothing to do here.\n\n```\nexec \"$SHELL\"   # or just open a new terminal\ncd <a directory linked to a Neon project>\nneon status --current-branch    # should print your branch, e.g. \"main\"\n```\n\nYou should now see `🌿 main`\n\n(or your branch) in the prompt. In a non-Neon directory, the\nsegment is simply absent.\n\n-\n**Symbol**—`symbol = \"🌿 \"`\n\n. Use any emoji, or a[Nerd Font](https://www.nerdfonts.com/)glyph if your terminal font has one (for example the database icon `` ). -\n**Color**—`style = \"bold green\"`\n\n(any Starship style string). -\n**Faster outside Neon projects (optional)**—`when`\n\nabove runs the CLI on every prompt everywhere (~25 ms each). To skip it entirely unless a`.neon`\n\nexists up the tree, replace`when`\n\nwith a pure-shell check that only invokes the CLI inside Neon projects. This`when`\n\nis POSIX-sh script, so add`shell = [\"sh\"]`\n\nto the block to ensure it runs under`sh`\n\neven if your interactive shell is fish or PowerShell:\n\n```\nshell = [\"sh\"]\nwhen = '''\nd=\"$PWD\"\nwhile [ \"$d\" != \"$HOME\" ] && [ \"$d\" != / ]; do\n  if [ -e \"$d/.neon\" ]; then\n    neon status --current-branch >/dev/null 2>&1\n    exit $?\n  fi\n  d=$(dirname \"$d\")\ndone\nexit 1\n'''\n```\n\n**Nothing shows up**— Confirm`neon status --current-branch`\n\nactually prints a branch in that directory. You need a pinned branch: run`neon link`\n\nthen`neon checkout <branch>`\n\n(this creates the`.neon`\n\nfile).**A bare icon with no branch name**— Make sure the`when`\n\nline is present; it hides the segment when there's no branch. This requires Neon CLI**≥ 2.28.0**(older versions exit 0 even with no branch). Update with`npm install -g neonctl`\n\n.**Prompt feels slow**— Ensure you're on Neon CLI ≥ 2.28.0 (it has a fast path for this command). If it still lags, raise Starship's timeout by adding`command_timeout = 1000`\n\nat the top of`starship.toml`\n\n, or use the \"Faster outside Neon projects\"`when`\n\nabove.— Run`neon: command not found`\n\n`npm install -g neonctl`\n\n(Node ≥ 22) and make sure your npm global bin directory is on your`PATH`\n\n.**The symbol renders as a box or**— Your terminal font lacks that glyph. Use a plain emoji, or install a`?`\n\n[Nerd Font](https://www.nerdfonts.com/).\n\nLearn more: [Neon CLI](https://neon.com/docs/reference/neon-cli) · [Starship custom commands](https://starship.rs/config/#custom-commands)", "url": "https://wpnews.pro/news/show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready", "canonical_source": "https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7", "published_at": "2026-06-29 21:31:43+00:00", "updated_at": "2026-06-29 22:48:26.014827+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Neon", "Starship", "Neon CLI", "neonctl"], "alternates": {"html": "https://wpnews.pro/news/show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready", "markdown": "https://wpnews.pro/news/show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready.md", "text": "https://wpnews.pro/news/show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready.txt", "jsonld": "https://wpnews.pro/news/show-your-neon-branch-in-your-terminal-prompt-starship-copy-paste-agent-ready.jsonld"}}