pithy alias

Install, remove, or report the p. shell shortcut for the pithy command line.

Synopsis

pithy alias [--json]
pithy alias --remove [--json]
pithy alias --status [--json]

Flags

FlagTypeDefaultMeaning
--removebooleanfalseUninstall the alias
--statusbooleanfalseReport whether the alias is installed
--jsonbooleanfalseMachine-readable output

No flags installs. --remove and --status are mutually exclusive.

What it does

Two characters, ending in the brand mark: p. init, p. add auth, p. deploy.

It detects the shell, from $SHELL plus the platform, and resolves where its alias line belongs.

Shellrc fileAlias syntax
bash~/.bashrc, or ~/.bash_profile on macOS when it existsalias p.='pithy'
zsh~/.zshrcalias p.='pithy'
fish~/.config/fish/config.fishalias p. pithy
nushell~/.config/nushell/config.nualias p. = pithy
PowerShellThe $PROFILE PowerShell itself reports: PowerShell 7 (pwsh)'s, and on Windows also Windows PowerShell 5.1’sfunction p. { pithy @args }

PowerShell gets a function rather than an alias because Set-Alias rejects a . in a name. On Windows its rc file is two files. PowerShell 7 (pwsh) loads one profile, Windows PowerShell 5.1 — which ships with Windows — loads another, and no file loads in both. So the block goes into both, and a family you have not installed holds an inert block until you do. pwsh on macOS or Linux has one profile.

Where each profile lives is PowerShell’s answer, not a guess. Documents may be redirected — OneDrive does it — and $PROFILE follows it. So pithy alias, --status, --remove and pithy doctor each ask every edition for its own $PROFILE, running it with -NoProfile, a 10-second timeout and no shell. On Windows, 5.1 runs from its System32 path, and pwsh only when PATH resolves it to an executable. An edition that cannot be run, exits non-zero, times out, or prints anything other than exactly one absolute .ps1 path falls back to its platform default:

EditionFallback
PowerShell 7 on Windows~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
Windows PowerShell 5.1~\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
pwsh on macOS and Linux~/.config/powershell/Microsoft.PowerShell_profile.ps1

A block an earlier version wrote to a guessed path that is not the one PowerShell reports — ~/Documents/PowerShell/… on macOS or Linux, or an un-redirected Documents on Windows — stays where it is. It is inert, --status does not read it, and --remove does not delete it; remove it by hand if you want it gone.

macOS bash prefers .bash_profile — the platform convention — and falls back to .bashrc only when it is absent.

It writes a delimited block, never a bare line:

# >>> pithy alias >>>
alias p.='pithy'
# <<< pithy alias <<<

Universal # comment syntax, and the markers are what --remove finds and deletes. Nothing outside them is touched.

pithy init** offers this once**, at the end of a scaffold and only to a human at a terminal — which is why most people never run this command themselves.

Idempotent. A second install detects the existing block — or a hand-added alias p.= in any form — and writes nothing. Where the rc file is two files, an install tops up the one without the block, which is how an install from before the second profile is repaired, and it names every file it wrote.

An unrecognized shell is never guessed at. It prints the POSIX form and how to add it by hand, then exits 0. It writes to no rc file it does not recognize.

--status reads only, and names the files that carry the block. It answers on the marker block alone, so a hand-added alias p.= reads as not installed — the command reports what --remove could act on, not what the shell happens to define.

Two hidden flags

Handled before the command dispatch, so neither is a subcommand and neither appears in --help.

pithy --pithier is a synonym for pithy alias. It installs, with the same output.

pithy --pithiest declines:

$ pithy --pithiest
Pithy enough.

Exit 0. No alias is installed. The refusal is the point.

Neither hidden flag takes --json.

--json

One line, one object. The shape follows the path taken, and there are four. command and action lead every one of them: alias has no subcommands, so action is what tells the paths apart.

$ pithy alias --json
{"command":"alias","schemaVersion":1,"action":"install","installed":true,"alreadyInstalled":false,"wrote":["/home/you/.bashrc"],"shell":"bash","rcPath":"/home/you/.bashrc","alias":"alias p.='pithy'"}

$ pithy alias --remove --json
{"command":"alias","schemaVersion":1,"action":"remove","removed":true,"removedFrom":["/home/you/.bashrc"],"rcPath":"/home/you/.bashrc"}

$ pithy alias --status --json
{"command":"alias","schemaVersion":1,"action":"status","installed":true,"installedIn":["/home/you/.bashrc"],"shell":"bash","rcPath":"/home/you/.bashrc"}

$ pithy alias --json
{"command":"alias","schemaVersion":1,"action":"install","shell":null,"manual":true,"alias":"alias p.='pithy'"}

That last one is the unknown-shell path. It used to carry no action at all — so the one case where the command exited 0 and changed nothing was the one case a consumer keying on action could not classify, and it is the case that most needs detecting.

KeyTypeMeaning
command"alias"The command that produced the line. On every payload
schemaVersionintegerThe version of this payload’s shape. Bumped only by a change that breaks a parser — a key removed, a key retyped, a value added to a fixed set; an added key does not bump it. pithy schema publishes the current one
action"install", "remove" or "status"Which path ran. On every payload, the unknown-shell one included
installedbooleanInstall: always true — the alias is in place, whether this run put it there or found it. Status: whether the marker block is in any of the rc files
alreadyInstalledbooleanInstall only. true when the block, or a hand-added alias p.=, was already in one of the rc files before this run
wrotestring[]Install only, always present. The files this run wrote the block into. [] means nothing was written
removedbooleanRemove only. false when there was no block to remove — not an error, and the exit is 0
removedFromstring[]Remove only, present when removed is true. The files the block came out of
installedInstring[]Status only, present when installed is true. The files that carry the block
shellstring or nullThe detected shell family: bash, zsh, fish, nushell, powershell. null when detection failed
rcPathstring or nullAbsolute path to the rc file the alias line belongs in — the first, when there are two
rcPathsstring[]Present only when the rc file is more than one file — PowerShell on Windows. Every one, rcPath first
aliasstringThe alias line itself. The shell-specific syntax on the install path; the plain POSIX form on the unknown-shell path
manualtruePresent only on the unknown-shell path, and only from an install or a remove. Says the shell was not detected, nothing was written, and alias is for you to add by hand

installed, alreadyInstalled and wrote answer different questions on the install path: installed is the state afterwards, alreadyInstalled is whether the alias was there before, and wrote is what this run changed. On Windows a run can find the alias in one profile and write it into the other, so alreadyInstalled is true and wrote is not empty.

Errors

Both --remove and --status. The only error this command raises. Exit 2: the call is what to fix. Under --json it is one validation/invalid_input line on stderr, carrying "exit":2 and "retryable":false.

$ pithy alias --remove --status
Pass either --remove or --status, not both.
Choose one.

Nothing else here fails. An undetected shell, a missing rc file, and a remove with nothing to remove are all ordinary outcomes with exit 0.

Examples

$ pithy alias
Added `alias p.='pithy'` to /home/you/.zshrc
Open a new terminal, or run: source /home/you/.zshrc

$ pithy alias
Already pithy.

$ pithy alias --status
Installed in /home/you/.zshrc

$ pithy alias --remove
Removed `alias p.='pithy'` from /home/you/.zshrc
Open a new terminal, or run: source /home/you/.zshrc

$ pithy alias --remove
No Pithy alias installed.

A shell Pithy does not know:

$ pithy alias
Couldn't detect your shell.
Add `alias p.='pithy'` to your shell config to use `p.`.
ESC