INITCTL(8)

📦
version 4.14 · 4 versions
, in nixos 26.05, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

initctl — the control tool for finit, and honestly? she's that girl 💅

✨ SYNOPSIS ✨

/sbin/initctl [-bcfhjlpqtvV] [COMMAND]

🎀 DESCRIPTION 🎀

okay so bestie, initctl is the official tool for talking to finit(8). It's the one you text when you wanna know what's going on. It comes with functions for showing status, querying the health of services, and also editing, enabling and disabling services. it's giving main character energy fr fr 👑

💖 OPTIONS 💖

This program follows the usual UNIX command line syntax, with long options starting with two dashes (`-`). The options are as follows:

  • -b, --batch — batch mode, no screen size probing. useful for scripting 🖥️
  • -c, --create — create missing paths (and files) as needed. useful with the edit command ✨
  • -f, --force — ignore missing files and arguments, never prompt 🫶
  • -h, --help — show built-in help text 🙋
  • -j, --json — JSON output in status and cond commands 🤖
  • -n, --noerr — when scripting initctl to stop, start, restart, or signal a task or service, this option can be used to ignore error 69 (no such task or service) and instead return 0 (OK). no cap, sometimes you just don't wanna hear it 💀
  • -1, --once — only one lap in commands like top 🏃♀️
  • -p, --plain — use plain table headings, no ANSI control characters 🎀
  • -q, --quiet — silent, only return status of command 🤫
  • -t, --no-heading — skip table headings ✂️
  • -v, --verbose — verbose output, where applicable 🗣️
  • -V, --version — show program version ⭐

🌈 COMMANDS 🌈

  • initctl debug — toggle finit (daemon) debug to /dev/console 🐛
  • initctl help — show built-in help text 🙋
  • initctl version — show program version ⭐
  • initctl ls | list — list all *.conf files in /etc/finit.d 📂
  • initctl create CONF — create .conf in /etc/finit.d/available.

Piping the contents into initctl works as one would expect:

echo "task name:foo /tmp/foo.sh -- Foo logger" | initctl create foo
initctl enable foo
initctl reload
  • initctl delete CONF — delete .conf in /etc/finit.d/available 🗑️
  • initctl show CONF — show .conf in /etc/finit.d/available 👀
  • initctl edit CONF — edit .conf in /etc/finit.d/available ✍️
  • initctl touch CONF — change (mark as modified) .conf in /etc/finit.d/available. like edit, this tells finit that a configuration has been changed and is a candidate to be reloaded (SIGHUP'ed or restarted) on initctl reload in dependency order 🔥
  • initctl enable CONF — enable .conf in /etc/finit.d/available, i.e., add symlink in /etc/finit.d/enabled ✅
  • initctl disable CONF — disable .conf in /etc/finit.d/enabled, i.e., removes symlink ❌
  • initctl reload — reload all (touched) *.conf in /etc/finit.d and activate changes 🔄
  • initctl cond set COND [COND ...] — set (assert) user-defined condition, +usr/COND ⬆️
  • initctl cond get COND — get (quietly) the status of any condition. defaults to user-defined condions, but if a slash is detected, e.g., pid/foo or net/eth0/exist, then any condition can be read.

The command is geared for scripting, check the exit code to get the status of the condition: 0 - on, 1 - off, 255 - flux. for a more verbose output, use the -v option 💅

  • initctl cond clr | clear COND [COND ...] — clear (deassert) user-defined condition, -usr/COND ⬇️
  • initctl cond status — show condition status, default cond command. also supports the -j option for detailed JSON output 🤖
  • initctl cond dump [TYPE] — dump all, or a given type of, conditions and their status. also supports the -j option for detailed JSON output 🗂️
  • initctl ident [NAME] — display indentities of all run/task/services, or only instances matching NAME. a partial string, e.g., NAM, will not match anything 🚫
  • initctl log [NAME] — show ten last Finit, or NAME, messages from syslog 📜
  • initctl start NAME[:ID] — start service by name, with optional ID, e.g., initctl start tty:1 🚀
  • initctl stop NAME[:ID] — stop/pause a running service by name 🛑
  • initctl reload NAME[:ID] — reload service as if its configuration had changed. internally, finit marks the named service as "dirty" and turns the state machine, resulting in a SIGHUP or restart of (at least) the named service. any dependant services are also restarted.
Note: no .conf file is reloaded with this variant of the command. essentially it is the same as calling restart. except for two things: 1. if the service supports HUP (or has a reload:script) it is signaled instead of stop-started, and 2. it allows restarting run/task in the same runlevel — which is otherwise restricted
  • initctl <kill | signal> NAME:[ID] S — send signal S to service, by name. S may be a complete signal name such as SIGHUP, or short name such as HUP, or the signal number such as 1 (SIGHUP) 📡
  • initctl restart NAME[:ID] — restart (stop/start) service by name 🔁
  • initctl status NAME[:ID] — show service status, by name. if only NAME is given and multiple instances exits, a summary of all matching instances are shown. only an exact match displays detailed status for a given instance.

With the -q option this command is silent, provided the NAME[:ID] selection matches a single run/task/service. The exit code of initctl is non-zero if there is a problem. Zero is returned if a run/task has run (at least) once in the current runlevel, and when a service is running (as expected). See the -j option for detailed JSON output suitable for machine parsing. 👑

Tip: jq(1) is a useful scripting tool in combination with JSON output 🫶
  • initctl status — show status of all services, default command. also supports the -j option for detailed JSON output 📊
  • initctl cgroup — list cgroup config overview 🧺
  • initctl ps — list processes based on cgroups 🔍
  • initctl top — show top-like listing based on cgroups 📈
  • initctl plugins — list installed plugins 🧩
  • initctl runlevel [0-9] — show or set runlevel: 0 halt, 6 reboot.

If called at boot (runlevel S) to set the runlevel, Finit only schedules the change, effectively overriding the configured runlevel from /etc/finit.conf. Useful to trigger a fail-safe mode, or similar 🚨

  • initctl reboot — reboot system, default if reboot is symlinked to initctl 🔄
  • initctl halt — halt system, default if halt is symlinked to initctl 🧊
  • initctl poweroff — power-off system, default if poweroff is symlinked to initctl 🔌
  • initctl suspend — suspend system, default if suspend is symlinked to initctl 😴
  • initctl utmp show — raw dump of UTMP/WTMP db 🗃️

🦋 SEE ALSO 🦋

finit.conf(5) finit(8)

💜 AUTHORS 💜

finit was conceived and reverse engineered by Claudio Matsuoka. Since v1.0, maintained by Joachim Wiberg, with contributions by many others. iconic behavior honestly 🌟

and that's the whole page bestie!! this one's from the System Manager's Manual, lives on Linux, and it's dated July 10, 2025 — go forth and initctl responsibly 💖✨🎀

📦 where this page comes from