.Dd July 1, 2020
.Dt CRYPTEXCTL-DEVICE 1
.Os Darwin
.Sh NAME
.Nm cryptexctl device
.Nd manage connections to devices running the cryptex subsytem
.Sh SYNOPSIS
.Nm
device
.Ar ACTION
.Sh DESCRIPTION
Perform actions on a connected device. This subcommand will, when appropriate, trigger
the pairing dialog on the connected device.
.Sh OPTIONS
A list of actions which may be performed:
.Bl -tag -width -indent
.It Ar print
Print information about a connected device. This includes information about the
device name, UDID and various device identifiers used for personalization
.Pq see Xr cryptexctl-create 1 .
.It Ar pair
Initiate pairing cryptexctl on this machine with a device. This will trigger a pairing
dialog on the device which must be accepted before other cryptex operations, such as
installation, may be performed.
.Pp
The pair action will return immediately if the device has already been paired.
.It Ar unpair
Remove the pairing between this machine and a device. Performing future cryptex operations
will require the device be paired again.
.It Ar list
List devices on which cryptexctl may be able to operate. These devices may be connected
via a physical cable or over the network if remote lockdown is enabled. This is one way to
retrieve the device UDID, which is required to select the device on which to operate when
using other commands.
.El
.Sh ENVIRONMENT
.Bl -tag -width CRYPTEX_UDID
.It Ev CRYPTEXCTL_UDID
Read by
.Nm
to set the
.Fl -udid
option on the base
.Xr cryptexctl 1
command. This UDID value can be retrieved from the
.Em list
or
.Em print
actions and provides a convenient way to operate on a
single device when multiple devices are connected.
.Pp
The magic value
.Qq first
will select the first discovered device.
Note that this will select the
.Em first
device detected over the lockdown protocol. This may
include
.Em wireless
devices and the ordering is not guaranteed. It is
usually best to use a specific UDID.
.El
.\" .Sh TROUBLESHOOTING
.Sh SEE ALSO
.Xr cryptexctl 1 ,
.Xr cryptexctl-create 1
.Sh HISTORY
Introduced in macOS 11.0
.\" .Sh BUGS            \" Document known, unremedied bugs