.TH COSU 1 "February 2026" "cosu 1.1.0" "User Commands"
.SH NAME
cosu \- conditionally execute commands with sudo based on file permissions
.SH SYNOPSIS
.B cosu
[\fIOPTIONS\fR] [\fIFLAG PATH\fR]... \fB--\fR \fICOMMAND\fR [\fIARGS\fR...]
.SH DESCRIPTION
.B cosu
(conditional su) intelligently determines whether to run a command with
.BR sudo (8)
based on file permission checks. It checks if the current user has the specified
permissions on given paths, and only escalates privileges when necessary.
.PP
If any permission check fails, the entire command is executed with
.BR sudo .
If all checks pass, the command runs normally without privilege escalation.
.SH OPTIONS
.TP
.BR \-h ", " \-\-help
Display help message and exit.
.TP
.B \-\-version
Print version information and exit.
.SH FLAGS
The following flags specify which permissions to check on the subsequent path.
Multiple flags can be specified before a single path. Short flags can be
combined in a single argument (e.g.,
.B \-rw
is equivalent to
.BR "\-r \-w" ).
.TP
.BR \-r ", " \-\-read
Check if the current user has read permission on the following path.
.TP
.BR \-w ", " \-\-write
Check if the current user has write permission on the following path.
.TP
.BR \-x ", " \-\-execute
Check if the current user has execute permission on the following path.
.SH ARGUMENTS
.TP
.I PATH
A file or directory path to check permissions against. Must be preceded by
at least one permission flag.
.TP
.B \-\-
Separator that marks the end of
.B cosu
arguments and the beginning of the command to execute.
.TP
.I COMMAND
The command to execute, with or without sudo depending on permission checks.
.TP
.I ARGS
Optional arguments passed to the command.
.SH EXAMPLES
.PP
Check Docker socket permissions before running docker:
.PP
.nf
.RS
cosu \-rw /var/run/docker.sock \-\- docker ps
.RE
.fi
.PP
Check Incus socket permissions:
.PP
.nf
.RS
cosu \-rw /var/lib/incus/unix.socket \-\- incus list
.RE
.fi
.PP
Edit a configuration file, escalating only if needed:
.PP
.nf
.RS
cosu \-w /etc/nginx/nginx.conf \-\- vim /etc/nginx/nginx.conf
.RE
.fi
.PP
Check multiple paths before executing a command:
.PP
.nf
.RS
cosu \-r /etc/app/config \-w /var/log/app.log \-\- /opt/app/run
.RE
.fi
.PP
Check multiple permissions on a single path:
.PP
.nf
.RS
cosu \-rw /var/lib/database \-\- psql \-U postgres
.RE
.fi
.PP
Combine all three permission checks:
.PP
.nf
.RS
cosu \-rwx /opt/app/data \-\- /opt/app/run
.RE
.fi
.SH EXIT STATUS
.B cosu
exits with the status of the executed command.
.SH CREATING ALIASES
You can create shell aliases to automatically use
.B cosu
with frequently-used commands:
.PP
.nf
.RS
alias docker='cosu \-rw /var/run/docker.sock \-\- docker'
alias incus='cosu \-rw /var/lib/incus/unix.socket \-\- incus'
.RE
.fi
.SH FILES
None.
.SH ENVIRONMENT
.B cosu
inherits the environment of the calling shell. When executing with
.BR sudo ,
the environment is modified according to
.BR sudo 's
configuration.
.SH DIAGNOSTICS
.B cosu
will exit with an error message if:
.IP \(bu 2
No command is specified after the \fB\-\-\fR separator
.IP \(bu 2
No \fB\-\-\fR separator is found
.IP \(bu 2
A path is specified without preceding permission flags
.IP \(bu 2
An unknown flag is encountered
.SH SECURITY CONSIDERATIONS
.B cosu
only checks permissions, not ownership or group membership. The permission
checks use the standard test built-in, which respects ACLs and other
extended attributes.
.PP
When privilege escalation is needed,
.B cosu
uses
.BR exec (3)
to replace itself with
.BR sudo ,
preventing the creation of unnecessary intermediate processes.
.SH BUGS
Report bugs at: dev@sinitax.com
.SH AUTHOR
Written by cosu contributors.
.SH COPYRIGHT
Copyright \(co 2026 cosu contributors.
License MIT: <https://opensource.org/licenses/MIT>
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH SEE ALSO
.BR sudo (8),
.BR test (1),
.BR sh (1)