.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGCTL 8
.Os Hammerhead
.Sh NAME
.Nm zygctl
.Nd administrative control utility for zyginit
.Sh SYNOPSIS
.Nm
.Ar command
.Op Ar argument
.Sh DESCRIPTION
.Nm
is the administrative command-line interface for the
.Xr zyginit 8
service supervisor.
It communicates with the running
.Nm zyginit
daemon over a Unix domain socket to query service status,
start and stop services, and manage the enabled service set.
.Pp
Commands that modify the enabled service set
.Pq Cm enable , Cm disable
operate directly on the filesystem and do not require the daemon to be running.
All other commands connect to the daemon socket.
.Sh COMMANDS
.Bl -tag -width "restart"
.It Cm status Op Ar name
Display the status of all services, or of the named service if
.Ar name
is given.
Output includes the service name, current state, and if running,
the process ID and contract ID.
.It Cm start Ar name
Start the named service.
If the service is already running, a message is printed and no
action is taken.
.It Cm stop Ar name
Stop the named service.
The stop method is determined by the service definition: either
a contract-wide signal or execution of a stop command.
If the service does not stop within its configured timeout, it
is forcibly terminated with
.Dv SIGKILL .
.It Cm restart Ar name
Restart the named service.
If the service is running, it is stopped first.
If the service is stopped or in maintenance, it is started immediately.
.It Cm list
List all loaded service definitions with their type
.Pq daemon, oneshot, transient .
.It Cm enable Ar name
Enable a service for automatic start at boot.
Creates a symlink in
.Pa /etc/zyginit/enabled.d/
pointing to the service's TOML definition.
The service is not started immediately; use
.Cm start
to start it now.
.It Cm disable Ar name
Disable a service from automatic start at boot.
Removes the symlink from
.Pa /etc/zyginit/enabled.d/ .
The service is not stopped immediately; use
.Cm stop
to stop it now.
.It Cm log Ar name
Display the output log for the named service.
Service stdout and stderr are captured to per-service log files under
.Pa /var/run/zyginit/log/ .
Log files are truncated on each service start, so only the most recent
output is shown.
Useful for diagnosing startup failures.
.It Cm reload
Reload the service configuration.
The daemon re-scans
.Pa /etc/zyginit/enabled.d/
and compares with the current service table.
Newly-enabled services are started; disabled services are stopped.
This is equivalent to sending
.Dv SIGHUP
to the
.Xr zyginit 8
process.
.It Cm replace Op Fl -wait Ns = Ns Ar N
Replace the running
.Xr zyginit 8
process via in-place
.Xr execve 2
of
.Pa /sbin/init .
All running services keep running across the swap; their process
contracts, restart counters, and uptimes are preserved via a state
file at
.Pa /var/run/zyginit/state.toml .
The operator must drop the new binary at
.Pa /sbin/init
.Em before
issuing this command;
.Nm
does not stage or copy binaries.
.Pp
With
.Fl -wait Ns = Ns Ar N ,
poll up to
.Ar N
seconds for any service in a transient state
.Pq starting , stopping , waiting
to stabilize before refusing.
Default is
.Ar N
=
.Sy 0
(refuse immediately).
Useful for automation: run
.Nm
.Cm replace Fl -wait Ns = Ns Sy 60
to either succeed within a minute or fail with a known upper bound on
time.
.Pp
The replace flow is operator-driven only; it does not cover crash
recovery.
See
.Xr zyginit 8
for the full mechanism.
.It Cm version
Print the version of
.Nm .
.It Cm help
Print a summary of available commands.
.El
.Sh ENVIRONMENT
.Bl -tag -width "ZYGINIT_CONFIG_DIR"
.It Ev ZYGINIT_SOCKET
Path to the
.Xr zyginit 8
control socket.
Default:
.Pa /var/run/zyginit.sock
.It Ev ZYGINIT_LOG_DIR
Path to the per-service log directory.
Used by the
.Cm log
command.
Default:
.Pa /var/run/zyginit/log
.It Ev ZYGINIT_CONFIG_DIR
Path to the service definition directory.
Used by the
.Cm enable
and
.Cm disable
commands to locate TOML files and the
.Pa enabled.d/
subdirectory.
Default:
.Pa /etc/zyginit
.El
.Sh EXIT STATUS
.Nm
exits 0 on success.
If it cannot connect to the daemon socket, a diagnostic message is
printed to standard error.
.Sh EXAMPLES
Show the status of all services:
.Bd -literal -offset indent
$ zygctl status
sshd running pid=1234 ctid=7
cron running pid=1235 ctid=8
filesystem stopped
.Ed
.Pp
Show the status of a single service:
.Bd -literal -offset indent
$ zygctl status sshd
sshd running pid=1234 ctid=7
.Ed
.Pp
Stop and disable a service:
.Bd -literal -offset indent
# zygctl stop sshd
sshd stopping
# zygctl disable sshd
.Ed
.Pp
Enable and start a service:
.Bd -literal -offset indent
# zygctl enable sshd
# zygctl start sshd
sshd started
.Ed
.Pp
List all loaded service definitions:
.Bd -literal -offset indent
$ zygctl list
sshd (daemon)
cron (daemon)
network (oneshot)
filesystem (oneshot)
.Ed
.Sh SEE ALSO
.Xr zyginit 8 ,
.Xr zyginit 5
.Sh HISTORY
.Nm
first appeared in Zygaena/Hammerhead alongside
.Xr zyginit 8 .
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com