XCreds Command Line Interface Guide

XCreds provides a command line interface that can be used to check XCreds status, securely store local admin credentials to help with user password reset, and to configure user info for logging in with RFID cards.

Setup

The command line interface is run using Terminal by referencing the following path in the XCreds app bundle.

/Applications/XCreds.app/Contents/MacOS/XCreds

Most XCreds CLI commands will require sudo so it may be best to run it from a secure shell.

sudo -s

For convenience it may also be helpful to create an alias for the CLI path.

alias xc=/Applications/XCreds.app/Contents/MacOS/XCreds

View Help Information

To begin, run the help option to view help.

xc -h

This will show the following help information on the commands available.

OVERVIEW: Command line interface for XCreds.

USAGE: xcreds <subcommand>

OPTIONS:
  -h, --help              Show help information.

SUBCOMMANDS:
  status                  Get status of XCreds
  import-rfid-users       Import users from a CSV for RFID login. Format:Full Name,Username,Password,RFID-UID,PIN,UID. PIN and UID can be left blank. All imported user data is encrypted and stored in a file located in /usr/local/var/twocanoes. The file is only readable by root.
  show-template           Template for importing RFID users. The header row is optional. PIN and UID can be left blank but must contain commas with empty values as show below. John Doe has all values, Sam Doe does not have a PIN, and Jane Doe does not have a PIN or a UID (UID will be automatically selected when the user account is created)
  set-rfid-user           Add an RFID user.
  show-rfid-user          Show RFID user.
  show-rfid-users         Show RFID users.
  remove-rfid-user        Remove RFID user by rfid-uid.
  set-admin-user          Set the current admin user used for resetting keychain.
  show-admin-user         Show currently set admin user. Used for resetting keychain.
  clear-admin-user        Clear the current admin user used for resetting keychain.
  clear-rfid-users        Clear all users. Does not clear the admin user.
  list-readers            List currently plugged in RFID readers.
  rfid-listener           Listen and print the RFID of scanned cards.
  run-app (default)       Start app normally.

  See 'xcreds help <subcommand>' for detailed help.

XCreds Status

The status command returns a variety of information about XCreds that may be helpful for managing a group of Macs. This will include information about XCreds current version, license expiration, recent login success/failure info, and more. The output for this status info can optionally be requested in JSON format.

OVERVIEW: Get status of XCreds

USAGE: xcreds status [--json] [<other> ...]

Set Admin User

The XCreds command line interface can be used to securely store an existing macOS admin’s credentials to help with user password reset. If a user signs in to XCreds with their cloud password and it has changed recently, they will be asked for their prior local password. If they do not know their prior local password, XCreds will prompt for an admin user to enter credentials to approve a password reset. In some situations it can be preferable to instantly approve the password reset without requiring assistance from an admin. More information on security for this is available: XCreds Local Secrets Cryptography.

Set Admin User

OVERVIEW: Set the current admin user used for resetting keychain.

USAGE: xcreds set-admin-user --adminusername <adminusername> --adminpassword <adminpassword>

OPTIONS:
  --adminusername <adminusername>
                          Update Admin username
  --adminpassword <adminpassword>
                          Update Admin password

Clear Admin User

OVERVIEW: Clear the current admin user used for resetting keychain.

USAGE: xcreds clear-admin-user

Configure User Info for RFID Card Login

XCreds can allow users to sign in with an RFID card. This can be done by using the command line interface to map RFID values to existing or new user accounts. More information on configuring RFID is available in the RFID Card Guide.

The CLI command import-rfid-users can be used to import a CSV file that contains information on users and RFID card values. When such a CSV file is imported, XCreds will store this information in a secure file at the following path.

/Volumes/Macintosh\ HD/usr/local/var/twocanoes/secrets.bin

XCreds encrypts the data stored in this file and places root-only file permissions on it. More information on security for this is available: XCreds Local Secrets Cryptography.

This information can then allow XCreds to map the RFID card values to the specified existing or new user accounts. If a card with an imported RFID value is later used to sign in, XCreds will create a new user account if necessary or allow the corresponding existing user to sign in.

Reader Information

The command line interface provides commands for getting information on the RFID reader used. First plug in an RFID reader, then use the list-readers command to get the name of the reader device. The reader name will need to be added to XCreds configuration using the preference key ccidSlotName.

OVERVIEW: List currently plugged in RFID readers.

USAGE: xcreds list-readers

The command line interface also provides the rfid-listener command to show information on RFID cards as they are read by the connected RFID reader. Run the rfid-listener command, swipe an RFID card on the reader, and view the card identification number that is read by the reader.

OVERVIEW: Listen and print the RFID of scanned cards.

USAGE: xcreds rfid-listener --reader-name <reader-name>

OPTIONS:
  --reader-name <reader-name>
                          reader name

Import RFID Users with CSV File

OVERVIEW: Import users from a CSV for RFID login. Format:Full Name,Username,Password,RFID-UID,PIN,UID. PIN and UID can be left blank. All imported user data is encrypted and stored in a file located in /usr/local/var/twocanoes. The file is only readable by root.

USAGE: xcreds import-rfid-users --file <file>

OPTIONS:
  --file <file>           file
  -h, --help              Show help information.

CSV Template

The command line interface can provide an example CSV format to use.

xcreds show-template

Other RFID Options

The command line interface also provides the following options to view or remove RFID user info for one or multiple users:

set-rfid-user
show-rfid-user
show-rfid-users
remove-rfid-user
clear-rfid-users

Usage

OVERVIEW: Add an RFID user.

USAGE: xcreds set-rfid-user [<other> ...] --fullname <fullname> --username <username> --password <password> [--uid <uid>] --rfiduid <rfiduid> [--pin <pin>]

ARGUMENTS:
  <other>

OPTIONS:
  --fullname <fullname>   Update Fullname
  --username <username>   Update username
  --password <password>   Update Password
  --uid <uid>             Update UID
  --rfiduid <rfiduid>     Update RFID-uid
  --pin <pin>             PIN
  -h, --help              Show help information.
  
**********************

OVERVIEW: Show RFID user.

USAGE: xcreds show-rfid-user --rfid-uid <rfid-uid> [--pin <pin>]

OPTIONS:
  --rfid-uid <rfid-uid>   RFID-uid in hex with no 0x in front.
  --pin <pin>             PIN
  -h, --help              Show help information.
  
**********************

OVERVIEW: Show RFID users.

USAGE: xcreds show-rfid-users

OPTIONS:
  -h, --help              Show help information.
  
**********************

OVERVIEW: Remove RFID user by rfid-uid.

USAGE: xcreds remove-rfid-user --rfid-uid <rfid-uid>

OPTIONS:
  --rfid-uid <rfid-uid>   RFID-uid in hex with no 0x in front.
  -h, --help              Show help information.

**********************

OVERVIEW: Clear all users. Does not clear the admin user.

USAGE: xcreds clear-rfid-users

OPTIONS:
  -h, --help              Show help information.

---