---
name: "initctl"
section: "8"
platform: "linux"
package: "finit"
version: "4.12-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/initctl"
---

# initctl(8)

Control tool for Finit

## NAME

**initctl** – Control tool for Finit

## SYNOPSIS

**/sbin/initctl** \[**-bcfhjlpqtvV**\] \[COMMAND\]

## DESCRIPTION

**initctl** is the official tool for interacting with [finit(8)](/finit/8.md). It comes with functions for showing status, querying health of services, as well as editing, enabling and disabling services.

## 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).

- **-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 restarted (or SIGHUP'ed) on **initctl** **reload**

- **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 **\*.conf** **in** */etc/finit.d*, i.e., activates 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, it's signaled instead of stop-started, and

  2. it allows restarting run/task in the same runlevel -- which is otherwise restricted.

- **initctl** *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)](/jq/1.md) 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.conf/5.md) [finit(8)](/finit/8.md)

## AUTHORS

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