orphan

🇪🇸 Leer en castellano

A tiny cross-platform toolkit of two CLIs:

• orphan — run a command fully detached from the current shell, like at now but immediate.
• orphan-wait — pause until one or more PIDs have died, even if they are not children of the current shell (the shell builtin wait can't).

orphan "gitk -a"

That's it. The command is parsed by the system shell, runs under your user, in your current directory, and survives the terminal closing. orphan prints the detached process's PID and exits immediately.

Why?

Sometimes you want to launch a GUI app (gitk, emacs, an Electron tool) or a long-running script from a terminal you're about to close, without the ceremony of nohup ... & + disown, log redirections, or remembering the right combination of flags. And ideally, the same command should work on Linux, macOS, and Windows.

orphan is a single small binary that does exactly that.

Installation

Both options install two binaries into ~/.cargo/bin/: orphan and orphan-wait (.exe on Windows). Make sure ~/.cargo/bin is on your PATH.

From GitHub (no clone needed)

cargo install --git https://github.com/neitanod/orphan

From a local clone

git clone https://github.com/neitanod/orphan
cd orphan
cargo install --path .

Usage — orphan

orphan [OPTIONS] <COMMAND>

Arguments

Argument	Description
<COMMAND>	The command to run, as a single quoted string. Parsed by the system shell, so pipes, redirections, globs, quoting, and environment variables all work as you'd expect.

Options

Option	Description
--stdout <FILE>	Redirect the detached process's stdout to <FILE> (append mode). If omitted, stdout is discarded.
--stderr <FILE>	Redirect the detached process's stderr to <FILE> (append mode). If omitted, stderr is discarded.
-h, --help	Print help.
-V, --version	Print version.

Examples

# GUI app — no logs needed
orphan "gitk -a"

# Long build — capture both streams
orphan "long-build.sh" --stdout build.log --stderr build.err

# Pipelines and shell globs work
orphan "find / -name '*.tmp' | xargs rm" --stdout cleanup.log

# Use the printed PID later
PID=$(orphan "my-server --port 8080" --stdout server.log)
echo "Server PID: $PID"
# ... later ...
kill $PID

Usage — orphan-wait

orphan-wait [OPTIONS] <PID>...

Pauses until the given PIDs have died. Unlike the shell builtin wait, this works for processes that are not children of the current shell — which is exactly the case for processes launched with orphan.

Options

Option	Description
--timeout <SEC>	Maximum time to wait, in seconds (fractional values allowed). On timeout, exits with code 1.
--interval <MS>	Polling interval in milliseconds. Default 250.
--any	Return as soon as any of the PIDs dies, instead of waiting for all of them.
-v, --verbose	Print a line on stderr when each PID exits.
-h, --help	Print help.
-V, --version	Print version.

Exit codes

Code	Meaning
0	All PIDs (or one, with --any) finished.
1	Timeout reached.
2	Usage error.

Scripting example

Launch two long-running jobs detached, do some other work in the meantime, then block until both have finished:

#!/bin/bash
echo "this is a long running process"

# Capture the PIDs into shell variables — no tmpfiles needed.
PID1=$(orphan "long-build.sh" --stdout build.log --stderr build.err)
PID2=$(orphan "long-tests.sh" --stdout tests.log --stderr tests.err)

echo "doing other things in the meantime..."
sleep 5

# Block until BOTH detached jobs are done. Works even though they are
# not children of this shell.
orphan-wait "$PID1" "$PID2" --verbose

echo "both finished, continuing"

A few more patterns:

# Wait for the first one to finish (whoever wins).
orphan-wait "$PID1" "$PID2" --any

# Wait up to 30 seconds, then give up.
orphan-wait "$PID1" --timeout 30 || echo "timed out"

# Faster polling for short jobs (default is 250ms).
orphan-wait "$PID1" --interval 50

How it detects process death

Platform	Mechanism
Linux, macOS	kill(pid, 0) — returns ESRCH once the PID is gone.
Windows	OpenProcess + GetExitCodeProcess — STILL_ACTIVE means alive.

orphan-wait polls at the configured interval. For typical scripting loads (a handful of PIDs, sub-second precision) this is negligible. If you need event-driven precision (pidfd_open, kqueue, WaitForMultipleObjects), open an issue.

Note on PID recycling. PIDs can be reused by the OS once the original process dies. orphan-wait cannot distinguish between "PID X is still your original process" and "PID X is some new process that happens to have the same number". In practice this is exceedingly rare on modern systems with large PID spaces and short-ish waits, but be aware if you wait for hours on a busy system.

What the detached process inherits

Aspect	Inherited?
Working directory	✅ Yes — your current pwd.
User / permissions	✅ Yes — same uid as you.
Environment vars	✅ Yes — your full env.
stdin	❌ Disconnected (/dev/null / NUL).
stdout / stderr	❌ Discarded by default; redirect with --stdout / --stderr.
Controlling TTY	❌ Detached (that's the whole point).

Detach strategy

Unix (Linux, macOS)

orphan spawns the command via sh -c "<command>" and uses setsid(2) in a pre_exec hook before execve. This makes the child the leader of a new session with no controlling terminal, so it won't receive SIGHUP when the launching terminal closes. After orphan exits, the child is reparented to PID 1 (or the nearest subreaper, e.g. systemd --user).

Windows

orphan spawns the command via cmd /C "<command>" with the CreateProcess flags:

• DETACHED_PROCESS — no console attached.
• CREATE_NEW_PROCESS_GROUP — independent process group, immune to CTRL+C / CTRL+BREAK from the launcher.
• CREATE_BREAKAWAY_FROM_JOB — escapes any job object the launcher is in, so killing the launcher doesn't cascade.

Exit behavior

orphan itself exits as soon as the child is spawned:

• On success, it prints the child's PID on stdout and exits with code 0.
• On failure (bad --stdout/--stderr path, spawn error), it prints an error on stderr and exits with code 1.

orphan does not wait for the child and does not report the child's exit status. The child runs independently.

Comparison with similar tools

Launching detached

Tool	Cross-platform	Detaches TTY	Captures output	Notes
orphan	✅ Linux/macOS/Windows	✅	✅ via flags	This tool.
nohup cmd &	❌ Unix only	Partial	Default file	Needs &, still child of shell.
disown	❌ Bash/zsh	❌	❌	Shell builtin only.
setsid cmd &	❌ Linux	✅	❌	Linux-specific util.
at now	❌ Unix only	✅	Mail	Adds dependency on atd + mail.
start "" cmd	❌ Windows	Partial	❌	Console window still appears.

Waiting for non-child processes

Tool	Cross-platform	Waits for non-children	Notes
orphan-wait	✅ Linux/macOS/Windows	✅	This tool.
wait (builtin)	❌ Unix only	❌	Kernel won't let you waitpid() on a non-child.
tail --pid=PID	❌ Linux	✅	GNU-only; clever workaround using inotify on /proc/PID.
while kill -0	❌ Unix only	✅	Manual polling loop, easy to get wrong.

License

MIT.