J621/extras/powershell_greeting/README.md

PowerShell greeting (J621 Windows port)

Shows a random J621 library image as your shell greeting, using fastfetch. This is the Windows/PowerShell port of ../fish_greeting/ - same API, same modes, same logs, adapted to PowerShell 5.1+ and Windows terminals.

What changed from the fish version

	fish	PowerShell (this port)
Entry point	fish_greeting function	Show-J621Greeting (loaded from your profile)
Endpoint	GET /api/random/?fastfetch=1&rating=X	same
Config	~/.config/j621Greeting/config.fish	%APPDATA%\j621Greeting\config.ps1
Mode file	~/.config/fish/greeting_mode	%APPDATA%\j621Greeting\greeting_mode (the file gm-switch.exe writes)
JSON parsing	jq / python3 / grep	ConvertFrom-Json (built-in)
MIME detection	file --mime-type	PNG/JPEG/GIF magic bytes
GIFs	gifsicle + kitten icat	none: static first frame in Windows Terminal, animated in WezTerm (its kitty-direct plays the GIF)
fastfetch logo	--logo-type kitty --logo ... --logo-width 35	sixel in Windows Terminal, kitty-direct in WezTerm, no image elsewhere
Logs	~/.config/j621Logos/logs.log	%APPDATA%\j621Logos\logs.log

Install

cd extras\powershell_greeting
.\install.ps1

The installer copies J621Greeting.ps1 into %APPDATA%\j621Greeting\, asks for your API origin (and an optional scoped token), writes %APPDATA%\j621Greeting\config.ps1, wires a marker block into your PowerShell profile (it replaces the previous plain-fastfetch hook), checks the tools it needs and probes the backend (/health plus a random roll). It exits non-zero when the backend cannot be reached.

Non-interactive / re-install:

.\install.ps1 -Url https://j621.example.ts.net -Token <api-token>
.\install.ps1 -NoPrompt          # defaults, never asks
.\install.ps1 -Force             # rewrite an existing config
.\install.ps1 -NoProfilePatch    # do not touch your PowerShell profile
.\install.ps1 -Uninstall         # remove the profile block + installed script

Test it manually any time with:

Show-J621Greeting

Requirements: fastfetch and curl.exe (ships with Windows 10 1803+). Image logos need Windows Terminal 1.22+ (sixel) or WezTerm with kitty graphics enabled; other terminals fall back to a plain fastfetch.

No token? That is fine

The greeting is meant to run without a token: it then behaves like a guest of your instance - unsigned image links and only items that are visible to guests. Adding a token to the config unlocks signed links and items that are hidden from guests. The recommended value is a scoped greeting token: open the app, go to Account -> Shell tokens (or /tokens), create one and copy the j621r_... key - it only works with /api/random/, so it is safe to keep in the config file.

Configuration

%APPDATA%\j621Greeting\config.ps1 is read on every run (environment variables already set in your session win over it):

if (-not $env:J621_BASE) { $env:J621_BASE = 'https://j621.rainbow-herring.ts.net' }  # API origin
if (-not $env:J621_WEB)  { $env:J621_WEB  = 'https://j621.example.ts.net' }          # link origin (split deploys)
if (-not $env:J621_TOKEN) { $env:J621_TOKEN = '<api token>' }                        # signed URLs + hidden items
if (-not $env:J621_FASTFETCH_CONFIG) { $env:J621_FASTFETCH_CONFIG = 'jake' }         # fastfetch config name

Extra escapes (all optional):

• J621_LOGO_TYPE - force a fastfetch logo type (sixel, kitty-direct, ...)
• J621_ALWAYS_FETCH=1 - fetch even in terminals without image support (prints the link, ASCII logo)
• J621_LOGO_WIDTH - logo width in columns (default 35)
• J621_MODE_FILE - mode file override (shared with gm-switch)

Rating filters

greeting_mode	Rating requested	Label
0	e	NSFW
1	s	SFW
2 (default)	q	Questionable

The mode file is %APPDATA%\j621Greeting\greeting_mode. Use ../win-gm-switch/ (or its Start Menu shortcuts) to switch, or just edit the file.

Troubleshooting

• No image logo in Windows Terminal: WT 1.22+ is required for sixel; update with winget upgrade Microsoft.WindowsTerminal.
• WezTerm: kitty graphics must be on - config.enable_kitty_graphics = true in ~/.wezterm.lua. If the default looks wrong, try J621_LOGO_TYPE=kitty, sixel, or iterm.
• VS Code / other terminals: no image protocol, so the greeting prints a plain fastfetch on purpose (no fetch delay). J621_ALWAYS_FETCH=1 still fetches and prints the link.
• No logo (No image matches those filters.) - the library has no images for that rating; try another mode or add files.
• No logo (API error) - check J621_BASE and that the deployment is up (https://<host>/health).
• No logo (download failed) - the signed URL expired (they last 24 h) or the item was deleted between the two requests; just run it again.
• The greeting is slow - the API and image fetch have --max-time guards; a slow tailnet link is usually the cause.
• Log file: %APPDATA%\j621Logos\logs.log (only the last 1000 lines are kept).

gm-switch

The Rust ../win-gm-switch/ tool writes the same mode file, and on Linux it can replace the old C++ gm-switch (it writes ~/.config/fish/greeting_mode there, the same file the fish greeting reads).