Skip to content

just-runit

just-runit (alias: jbx) is an ephemeral bash tool runner. Fetch a script from a URL or namespace, call a function it defines, then discard — no installation, no leftover environment pollution. The bash equivalent of uvx, for anything reachable over HTTPS.

You are responsible for what you run

jbx fetches and executes arbitrary code from any URL you provide. It performs no review, scanning, or sandboxing of remote scripts. There is no safety guarantee of any kind — that responsibility belongs entirely to you. Always inspect a script before running it.

jbx just-bashit:datetime iso-8601-basic -m
# 20260522T174523.841Z

Getting just-runit

Source the install script — it downloads just-runit, creates jb, jbx, and just-buildit symlinks in ~/.local/bin, and exports the updated PATH into your current shell immediately (no new terminal needed):

. <(curl -sSL https://just-buildit.github.io/get-jb.sh)

That's it. jb and jbx are live in the shell you ran that in.

It also installs uv if it is missing, which Python scripts run through. It uses install-uv, so on Windows that means winget and the machine's native build, even from an emulated x64 Git Bash on ARM64. The directory uv lands in goes on your PATH right away.

For every later shell it runs update-path, which adds ~/.local/bin to ~/.bashrc, to ~/.zshrc when you have zsh, and on Windows to your user Path.

Use at your own risk

This script is provided as-is, without warranty of any kind. It writes to ~/.local/bin and may modify ~/.bashrc, ~/.zshrc and, on Windows, your user Path. The tool it installs runs arbitrary remote code with no safety guarantees — you are solely responsible for what you choose to run with it. Review the source before running: get-jb.sh

Why source instead of pipe to bash?

. <(...) runs the script in the current shell process, so export PATH=... reaches you directly. bash <(...) or curl ... | bash spawn a subshell — PATH changes die with it.

To force reinstall even when already at the current version:

JB_REINSTALL=1 . <(curl -sSL https://just-buildit.github.io/get-jb.sh)

update-path

jbx update-path

Puts ~/.local/bin on PATH for good, in every shell you have: where jbx lives, and where tools such as just-makeit's jm, uv and pipx link their commands. Installers that put a command there point you at it.

Shell Written to
bash ~/.bashrc
zsh ~/.zshrc, when zsh is installed or the file exists, and always on macOS
Windows your user Path in the registry (from Git Bash, and from PowerShell's jbx)

An rc file that already has an uncommented line naming .local/bin, or sources just-bashit's own bashrc.sh or profile.sh (which put it there), is left exactly as it is. Otherwise a marked block is appended:

# >>> just-bashit update-path >>>
case ":${PATH}:" in *":${HOME}/.local/bin:"*) ;; *) export PATH="${HOME}/.local/bin:${PATH}" ;; esac
# <<< just-bashit update-path <<<

The Windows directory is appended only when no entry of the user Path already expands to it; the other entries, unexpanded %VARS% included, and the value's type are kept. A re-run changes nothing anywhere. Each place gets one line saying what was written, or why nothing was:

update-path: ~/.bashrc: appended
update-path: ~/.zshrc: line 12 already covers it -- unchanged
update-path: Windows user Path: appended C:\Users\me\.local\bin (new windows see it)
update-path: this shell: jbx puts ~/.local/bin on PATH when this exits

Run through the jbx function -- jbx-shell in bash, and get-jb.ps1's in PowerShell -- the shell you ran it in gets the directory at once, through the reload marker. The script is update-path.sh: the bare name update-path is the default namespace's alias for it, and jbx just-bashit:update-path names it directly.

From PowerShell (Windows)

irm https://just-buildit.github.io/get-jb.ps1 | iex
jbx setup-system

get-jb.ps1 runs in Windows PowerShell 5.1 and PowerShell 7. jbx is bash, so bash is still what runs it — but as a runtime you never open:

  1. It finds Git for Windows' bash.exe (the registry, the git on PATH, then the default install directories) and never the WSL launcher in System32. With none, it installs Git.Git with winget (a machine-wide install, so one UAC prompt) and looks again.
  2. With no uv on PATH, it installs astral-sh.uv with winget, so an ARM64 machine gets the native build, and puts winget's Links directory on this session's PATH so bash sees it. On ARM64 winget also installs uv's dependency, the Arm64 Visual C++ Redistributable, which asks for elevation: expect one UAC prompt there.
  3. It runs get-jb.sh in that bash — the same installer as above, so a JB_REINSTALL=1 set in the session reaches it.
  4. It writes jbx and just-runit functions into a marked block of your profile and defines them in the current session. Re-running rewrites the block in place.

The block goes in the CurrentUserAllHosts profile of both editions — Documents\WindowsPowerShell\profile.ps1 and Documents\PowerShell\profile.ps1 — since they read different files and setup-system installs PowerShell 7 on a machine that has only 5.1. JB_PS_PROFILE names the file to use instead, or several separated like PATH (; on Windows).

A profile the installer cannot read is never written, since its content may exist nowhere else. The usual case: OneDrive was uninstalled, Documents still points at the OneDrive folder, and profile.ps1 there is an online-only file synced from another machine, which cannot be read without OneDrive. The installer names it with the fix, still writes the other profile and defines jbx in the current session, then fails naming each profile it skipped. To fix: recover the file from onedrive.com if you want its content, then delete the placeholder (or reinstall OneDrive so it downloads), and re-run the one-liner.

The functions forward arguments, piped input and the exit code ($LASTEXITCODE). Arguments travel in the environment to a small driver, %LOCALAPPDATA%\just-bashit\jbx-ps.sh, not on bash's command line, which the MSYS runtime would glob (*) and re-quote (', "): each one arrives as typed, empty ones included. Two things are PowerShell's own and happen before jbx sees anything: a bare -- is consumed by PowerShell, and an unquoted $name is expanded by it. An unquoted a,b is a PowerShell array, which the functions pass on as one argument a,b, so jbx setup-system -s sshd,git means what it does in bash. A profile written before that fix passed sshd git: re-run the one-liner to rewrite the block.

The functions also export JB_CALLER=pwsh for the call. setup-system reads it, so it ends by telling you to open a new PowerShell window when an install changed the Windows PATH, never to exec bash -l (closing advice).

PowerShell scripts

A script run in bash cannot change the PowerShell session that called it, so an installer that has to put a tool on your PATH cannot work through bash. So when a namespace serves a PowerShell script, jbx in PowerShell runs that, in your session:

jbx just-makeit:install      # install.ps1, in this session

The same command in bash runs install.sh, exactly as before. From PowerShell, NS:NAME (and a bare NAME) resolves in this order:

  1. NAME in the [aliases.ps1] table of the namespace's aliases.toml;
  2. a probe of NS_BASE/NAME.ps1;
  3. the bash resolution below — [aliases], NAME.sh, NAME.py — run in bash as before.

A URL form (https://…, gh:…, a repository URL) is run this way when it resolves to a URL ending in .ps1. just-bashit:NAME is a bash library and never is.

[aliases.ps1] is a table of its own, rather than a .ps1 URL in [aliases], because one name serves both shells:

[aliases]
install = "https://example.org/tools/install.sh"

[aliases.ps1]
install = "https://example.org/tools/install.ps1"

A jbx that predates it skips the table, as it skips any table but [aliases].

Resolution is jbx's own, in bash: the function hands it the call, and jbx resolves, fetches and caches the .ps1 as any script — the same cache, TTL, -r, -n, -t and -k — then hands it back instead of running it. The function runs it dot-sourced, with every argument after SPEC as you typed it: an unquoted a,b stays an array and -Name value binds by name. What it sets in $env: — PATH included — or with global: stays in your session; its plain variables do not leak. -l, -f and -c keep the bash resolution, since they list, fetch or run in a fresh process.

Before it runs, the script is parsed. A parse error, or an exit anywhere in it, is refused naming the URL: exit there would close your PowerShell window, not end the script. A script for jbx must be safe to irm | iex in the same way — it throws on failure. A throw is one error naming the URL, with $LASTEXITCODE 1; otherwise $LASTEXITCODE is 0, or what the script's last native command left.

The function that does this is in the profile block. A block written before it forwards every call to bash: re-run the one-liner to rewrite it.

Windows PowerShell 5.1 and the execution policy

5.1 runs a profile only when the execution policy allows scripts, and a fresh Windows client is Restricted. get-jb.ps1 warns rather than changing a security setting; jbx works in the session that ran it, and for new sessions run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. PowerShell 7's default already allows it.


How it works

jb run [OPTIONS] SPEC [FUNCTION [ARGS...]]
   or: jbx [OPTIONS] SPEC [FUNCTION [ARGS...]]

jbx resolves SPEC to a script URL, fetches it, sources it into a subshell, optionally calls FUNCTION with ARGS, then exits. The subshell boundary is the isolation — nothing leaks back to the calling shell.

Fetched scripts are cached at ${XDG_CACHE_HOME:-$HOME/.cache}/just-runit/ and reused on subsequent calls until the TTL expires (default 1 hour).


SPEC forms

Form Example Resolves to
NAME install-deps default namespace (just-buildit.github.io) via aliases.toml then direct probe
NS:NAME just-bashit:logging namespace NS — built-in, or your own
gh:USER/REPO/PATH gh:user/repo/tool.sh GitHub raw content, default branch main
gh:USER/REPO/PATH@REF gh:user/repo/tool.sh@v2.1.0 GitHub raw content at a specific ref/tag/SHA
https://... https://example.com/tool.sh Any HTTPS URL
[FORGE+]https://HOST/PROJECT//PATH[@REF] https://gitlab.com/acme/tools//ci/tool.sh@v2 A script by its path in a repository; see Repository URLs

Resolution order for NAME / NS:NAME:

  1. Look up NAME in the namespace's aliases.toml (cached)
  2. Probe NS_BASE/NAME.sh then NS_BASE/NAME.py
  3. Error if neither resolves

From PowerShell (the jbx function get-jb.ps1 writes), a PowerShell script comes first: NAME in the [aliases.ps1] table of the same aliases.toml, then a probe of NS_BASE/NAME.ps1, and only then the order above. See PowerShell scripts.

# Default namespace (just-buildit.github.io)
jbx install-deps -s apt

# Explicit just-bashit namespace
jbx just-bashit:logging log -t SUCCESS "deployed"

# Explicit just-makeit namespace
jbx just-makeit:install-deps

# GitHub shorthand, pinned to a tag
jbx gh:user/repo/scripts/deploy.sh@v1.4.0 run --env prod

# Full URL
jbx https://example.com/tools/setup.sh configure

# A script in a repository, on any supported forge
jbx https://gitlab.com/acme/tools//ci/deploy.sh@v1.4.0 run --env prod

just-makeit namespace

just-makeit:NAME is an ordinary URL-base namespace, like the default one, rooted at https://just-buildit.github.io/just-makeit. It holds the tools that just-makeit publishes for its own users, such as install-deps (the build-dependency installer). It resolves through that site's aliases.toml first, then the direct NAME.sh / NAME.py probe, and has no co-fetch bundle.

just-bashit namespace co-fetch

Libraries like logging and network depend on other just-bashit libraries. When you use just-bashit:NAME, jbx co-fetches the entire src/ directory into a single cache folder so relative inter-source calls resolve correctly — you don't have to manage this yourself.

Your own namespaces

Register a base once and its scripts get the same short form as the built-ins:

just-runit ns add examples gh:hunterdsp/examples/scripts
jbx examples:hello
# Hello World!

NAME:SCRIPT then resolves exactly as a built-in does: BASE/aliases.toml first, then BASE/SCRIPT.sh and BASE/SCRIPT.py. Caching, -r, -n, -k and the PowerShell hand-off all apply unchanged.

BASE Example
gh:USER/REPO[/DIR][@REF] gh:hunterdsp/examples/scripts@50b94ec
[FORGE+]https://HOST/PROJECT//DIR[@REF] https://gitlab.com/acme/tools//ci@v2
https://HOST/PATH https://tools.example.com/sh

gh: defaults to main and a repository URL to the default branch, as they do for a script. Pin a REF to pin the whole namespace: every script it serves then comes from that commit.

A base's REF has no / in it -- a tag, a commit or a branch such as main; ns add refuses gh:o/r/scripts@release/1.x. A gh: script SPEC takes one (jbx gh:o/r/t.sh@release/1.x fetches that branch); a base pins such a branch by its commit instead.

The repository chooses the short names, in an aliases.toml at BASE. It must serve one even if it is empty, as every built-in does — a base whose aliases.toml cannot be fetched is refused rather than probed (#164). A value with no : is a path relative to BASE, so it stays at a pinned REF:

[aliases]
hello = "hello-world.sh"                       # BASE/hello-world.sh
far   = "https://cdn.example.org/far.sh"       # used as written
just-runit ns add NAME BASE   # register; BASE is stored as the URL it names
just-runit ns list            # built-ins, then yours
just-runit ns rm NAME         # remove one of yours

They are kept in ${XDG_CONFIG_HOME:-~/.config}/jb/namespaces, one NAME BASE-URL per line. A built-in name cannot be added or removed, and a built-in always resolves first, so a hand-edited line cannot redirect just-bashit: or the default namespace. gh is not a namespace name: it is the GitHub shorthand.

Repository URLs

Name a script by the repository it lives in and its path there, instead of by a host's raw-content URL:

[FORGE+]https://HOST[:PORT]/PROJECT//PATH[@REF]
  • // separates the repository from the path inside it. It cannot be a colon, since the scheme and a port already use one. A URL path never holds //, so an ordinary script URL keeps its meaning.
  • @REF is a branch, tag or commit SHA. Without it, jbx fetches HEAD, the repository's default branch. (gh: keeps its main default.) A ref containing / is refused, because a raw URL cannot tell it from the path; pin a tag or SHA instead.
  • FORGE+ says which forge serves the host. The four public hosts below need no prefix. Any other host must name its forge, because jbx does not guess a raw-file layout. An unknown host is refused, and the error says which prefix to add.
FORGE Known host Fetches Covers
github github.com raw.githubusercontent.com/O/R/REF/PATH (another host: HOST/O/R/raw/REF/PATH) GitHub, GitHub Enterprise Server
gitlab gitlab.com HOST/GROUP/.../PROJECT/-/raw/REF/PATH GitLab.com, self-managed GitLab; nested groups
gitea or forgejo codeberg.org HOST/O/R/raw/REF/PATH Gitea, Forgejo, Codeberg
bitbucket bitbucket.org bitbucket.org/O/R/raw/REF/PATH Bitbucket Cloud only
jbx https://github.com/acme/tools//bin/tool.sh                 # default branch
jbx https://codeberg.org/acme/tools//tool.sh@v2 say hi         # a tag, then fn + args
jbx gitea+https://git.example.com:3000/ops/tools//deploy.sh@0123abc deploy
jbx gitlab+https://gitlab.example.com/platform/ci/tools//lint.sh

The repository URL resolves to the raw URL in the table, which is then fetched like any other URL. Caching, -r, -n, -k HASH, -f, -l, --no-verify, function calls and argument forwarding all behave as they do for a plain URL.

Transports and authentication. Fetching is HTTPS only, and the TLS certificate is checked. jbx sends no credentials and fetches straight from the host, never through a third-party service, so a private repository fails as it would for an anonymous browser. These are refused, each with an error saying what to use instead:

  • http://, ssh:// and git@host: URLs;
  • credentials in the URL (user:token@host), which would otherwise be written to logs and cache metadata;
  • Bitbucket Server and Data Center, which serve raw files on another layout;
  • an empty or absolute path, or one containing ..;
  • a repository that is not OWNER/REPO, except for GitLab groups.

Options

Flag Description
-l List functions the script defines, then exit (see below)
-f Fetch only — cache the script, print its path, run nothing
-r Refresh — re-fetch even if the cache is fresh
-n No-cache — fetch fresh, discard on exit; the cache is untouched
-c Clean environment (minimal env, like sudo without -E)
-p VARS Comma-separated vars to pass through when using -c
-t TTL Cache TTL in seconds. Default 3600. 0 = keep forever
-k HASH Verify before running: sha256:HASH or md5:HASH
-v Verbose — prints fetch/cache activity to stderr
--no-verify Skip TLS certificate checks on jbx's own downloads (see below)
-h, --help This help. After SPEC, either one goes to the script instead

--no-verify

Some networks re-sign TLS with a CA of their own, usually a proxy that inspects traffic. On a box that does not trust that CA, every jbx download fails with a certificate error. --no-verify makes jbx's own downloads skip the check, as curl --insecure does. That covers the script, the aliases.toml lookup, the just-bashit co-fetch bundle, the probe that resolves a bare name, and the nested uv install (JB_NO_VERIFY=1 carries it to install-uv's download). It prints a warning on every run.

jbx --no-verify -k sha256:abc123def456 https://example.com/tool.sh run
  • It has no short form, since -k is the checksum, so it is hard to type by accident. It is read only before SPEC: jbx tool.sh --no-verify passes the flag to the script.
  • Without TLS checks, anything on the path can change what is downloaded. Pin -k HASH so the script is still verified before it runs.
  • It changes only the downloads jbx makes. A script that fetches more (install-deps, setup-system) does so with its own curl and the box's CA store, so trusting the CA is the lasting fix.

Cache

Scripts are cached at ${XDG_CACHE_HOME:-$HOME/.cache}/just-runit/ and shared across all projects on the machine.

Layout

~/.cache/just-runit/
  <sha256>.sh          # cached script (key = SHA-256 of URL)
  <sha256>.meta        # sidecar: ts=<unix epoch>  url=<original URL>
  aliases-<sha256>.toml  # cached aliases.toml per namespace
  jbs/                 # just-bashit co-fetch bundle
    logging.sh
    network.sh
    ...

-n neither reads nor writes any of it: the script, the co-fetch bundle and aliases.toml go to a temporary directory under $TMPDIR, removed when the run exits.

The key is a SHA-256 of the full URL, so two different URLs that happen to return the same content get separate entries.

TTL

Default TTL is 3600 s (1 hour). Override per-invocation with -t SECONDS. -t 0 disables expiry — the entry is kept until manually removed or -r is used.

Inspect a cached entry

# See which URL a cache file came from and when it was fetched
cat ~/.cache/just-runit/<sha256>.meta
# ts=1779583354
# url=https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/just_bashit/install-deps.sh

Force a fresh fetch (keep the entry, overwrite it)

jbx -r just-bashit:install-deps --dry-run

Fetch once, write nothing to disk

jbx -n https://example.com/tool.sh run

Purge a single entry

jb cache clear https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/just_bashit/install-deps.sh

Or manually — find the hash with -v then remove the pair:

jbx -v install-deps 2>&1 | grep 'cache hit'
# jbx: cache hit: /home/you/.cache/just-runit/1f6227a...sh

rm ~/.cache/just-runit/1f6227a...{sh,meta}

Purge the just-bashit bundle (re-fetched as a unit on next use)

jb cache clear jbs

Purge everything

jb cache clear

Recipes

Discover what a script exposes before calling it:

jbx -l just-bashit:logging
# color-echo
# is-number
# iso-8601-basic
# log
# log-wait
# trim-from

-l lists a shell script's functions by reading it: nothing in the script runs, not its top-level commands and not the command substitutions in its assignments, so it lists any script, main guard or not:

jbx -l just-bashit:setup-system   # lists; sets nothing up

It lists the functions defined at the script's top level and inside a top-level if, then those of each file the script sources (source FILE / . FILE), read the same way. A sourced file is found from its path as written, never by evaluating it: a literal path as it is, and a path built from an expansion, such as source "${_SCRIPT_DIR}/toml.sh", by its last component beside the script, which is where jbx co-fetches a just-bashit script's libraries. One it cannot find is named on stderr and its functions are not listed. A Python script is parsed (ast), never run.

Running is the other half of the same contract: jbx SPEC and jbx SPEC FUNCTION both run the script's top level exactly once, as sourcing it would. A FUNCTION the script does not define exits 127.

Pin to a checksum for auditable CI use:

jbx -k sha256:abc123def456 https://infra.example.com/bootstrap.sh setup

Clean environment — script sees only HOME, TERM, PATH:

jbx -c https://example.com/tool.sh run

Pass specific vars into a clean environment:

jbx -c -p DEPLOY_TOKEN,AWS_REGION https://example.com/deploy.sh run

Force a fresh fetch (e.g. after a release):

jbx -r just-bashit:logging log "refreshed"

Skip the cache entirely — nothing touches disk:

jbx -n https://example.com/ephemeral.sh do-thing

Script mode — no function name, just source and run:

jbx https://example.com/setup.sh   # runs whatever the script does top-level

One-liner in CI:

jbx just-bashit:network test-internet-access -vt 10 || exit 1

Names

The installer creates two names in ~/.local/bin:

Name Type Takes subcommands?
just-runit binary yes
jbx symlink no

The difference is deliberate. just-runit accepts the subcommands below and falls through to the SPEC runner when the first argument is not one of them; jbx never treats an argument as a subcommand. So a script genuinely named install, cache or secret is always reachable as jbx install — no SPEC is shadowed by a keyword.

jb and just-buildit are not runner names

They were until 0.5.0, which put one token on three different things: the GitHub org, the just-buildit PEP 517 build backend, and this runner. The backend keeps the name — it is the one that actually builds. The installer prunes both aliases on upgrade.


Subcommands

These are available under just-runit only.

just-runit install

Walk up from the current directory to find bootstrap.toml, then pre-fetch every source declared under [tools.*] into the local cache. Subsequent jbx calls for those tools are instant cache hits. Nothing is run: each tool is fetched as just-runit -f fetches it.

  reading /path/to/project/bootstrap.toml
  -> just-bashit:install-deps ok

A legacy jb.toml met on the walk, before any bootstrap.toml, is refused with the rename to make. See bootstrap.toml.

just-runit install --no-verify fetches every tool with --no-verify.

just-runit ns

Add, list and remove your own namespaces.

just-runit cache

just-runit cache clear           # remove everything under ~/.cache/just-runit/
just-runit cache clear jbs       # remove the just-bashit co-fetch bundle only
just-runit cache clear <url>     # remove the entry for one specific URL
just-runit cache -h              # show cache subcommand help

just-runit secret

Stores a secret encrypted with gpg or age and hands it to one command, so a token no longer sits in a plaintext file or a shell profile that exports it to every process.

printf '%s' "$TOKEN" | just-runit secret set GH_TOKEN   # or type it at the prompt
just-runit secret run GH_TOKEN=GITHUB_TOKEN -- gh auth status
just-runit secret get GH_TOKEN | wl-copy
just-runit secret list
command does
set NAME [--backend gpg\|age] encrypts stdin, or what you type at a no-echo prompt on a terminal; never an argument; an empty value is refused and stores nothing
get NAME [--show] writes the value to stdout; refuses a terminal unless --show
run NAME[=VAR]... -- CMD [ARGS...] execs CMD with each secret in its environment, as VAR (default NAME)
list names and backends, never values
rm NAME... deletes
migrate NAME --to gpg\|age re-encrypts with the other backend
rekey [NAME...] re-encrypts to the recipients the config names now (default: every secret)

The store is ${XDG_DATA_HOME:-~/.local/share}/jb/secrets/, directory mode 700, one NAME.gpg or NAME.age per secret at mode 600. The extension is the backend: every command but set reads it off the file, so a store holding both kinds works whatever the default is. set on a secret already stored keeps its backend unless --backend says otherwise.

The config is ${XDG_CONFIG_HOME:-~/.config}/jb/secrets/recipients, one KEY VALUE per line, # starting a comment line:

gpg 0123456789ABCDEF0123456789ABCDEF01234567  # a full gpg fingerprint
age age1qyqszqgpqyqszqgp...     # an age recipient
age ~/.ssh/id_ed25519.pub       # a recipients file: age reads ssh keys too
identity ~/.config/jb/age.key   # what age decrypts with (age-keygen's output,
                                #   or an ssh private key)
default_backend age

A gpg line is a full 40-hex fingerprint (gpg --fingerprint KEY): a short key id is refused, since short ids collide. An age value is a recipient or an absolute path (~/ counts); a bare word that is neither is refused, and a relative path is never looked up, so a file planted in the directory you run from cannot choose the key.

The recipients file must be mode 600, and yours; its directory (~/.config/jb/secrets) must be yours and not writable by group or world (700); an identity file must not be readable by them. Each refusal is one error: line naming the chmod that fixes it. An editor running under umask 002 -- the default for a login on Debian and Fedora -- creates the recipients file as 664, which is refused: chmod 600 it once. A symlinked file (a stow-style dotfile) is judged by the file it points to. Windows (MSYS2, Git Bash) has no Unix modes, so these checks are skipped there.

With no gpg line, gpg encrypts to your own key. With no default_backend, set uses gpg when you have a gpg secret key, else age. An unknown key is an error, not a skipped line, so a typo cannot leave a recipient out.

What it guarantees:

  • No secret value is ever an argument -- not of just-runit, gpg or age. It goes in on stdin and comes out on a pipe.
  • migrate and rekey replace a file only once the new copy decrypts to the same bytes; any failure leaves the original as it was.
  • Shell tracing (SHELLOPTS=xtrace, a BASH_ENV that runs set -x) is turned off before any value is handled, so no trace shows one.
  • run refuses a VAR that changes how CMD runs: PATH, LD_*, DYLD_*, BASH_ENV, ENV, SHELLOPTS, BASHOPTS, IFS, PS4, BASH_XTRACEFD.
  • run decrypts every secret before it exports any, then execs CMD: CMD is the only process given them, not gpg, age, or the shell you ran it from. Trailing newlines are dropped, as $(...) drops them.
  • A missing tool, a missing key and no recipients are each one error: line naming what to install or configure, never a gpg or age dump, and no error message carries a value.

setup-system -s deps installs gpg and age.

just-runit version

Prints just-runit vX.Y.Z and exits.

just-runit help

just-runit help
just-runit -h
just-runit            # bare invocation also prints help