docs: how-to guides for user management

Author: thekaveman

docs/guides/user/backupcodes.md

@@ -0,0 +1,25 @@
+# How to Get a User's 2FA Backup Codes
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user backupcodes` reference section](../../reference/cli/user.md#compiler-admin-user-backupcodes).
+
+This guide explains how to use the `compiler-admin user backupcodes` command to get a list of active 2-Step Verification backup codes for a user.
+
+This can be useful if a user has lost their primary 2FA device and any recovery options.
+
+## Basic Usage
+
+To get backup codes for a user, provide their `username`.
+
+```bash
+compiler-admin user backupcodes some.user
+```
+
+The command will perform the following actions:
+
+1. Check if the user has existing backup codes.
+2. If they do, it will print them.
+3. If they do not, it will generate a new set of backup codes and print them.
+
+The output will be a list of the user's one-time-use backup codes.

docs/guides/user/convert.md

@@ -0,0 +1,44 @@
+# How to Convert a User's Account Type
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user convert` reference section](../../reference/cli/user.md#compiler-admin-user-convert).
+
+This guide explains how to use the `compiler-admin user convert` command to change a user's account type.
+
+This process moves the user between organizational units (OUs) and updates their group memberships (e.g., adding or removing them from the "Staff" or "Partners" groups).
+
+## Basic Usage
+
+To convert a user, you must provide their `username` and the target `account_type`.
+
+```bash
+compiler-admin user convert some.user staff
+```
+
+This command would convert `some.user@compiler.la` to a "Staff" account.
+
+## Available Account Types
+
+The following target account types are available:
+
+- `staff`: For full-time staff members.
+- `partner`: For partners of the company.
+- `contractor`: For external contractors.
+- `alumni`: For former employees. This is typically handled by the `offboard` command automatically.
+
+## Forcing the Conversion
+
+The command will ask for confirmation before proceeding. To bypass this, you can use the `--force` flag.
+
+```bash
+compiler-admin user convert some.user contractor --force
+```
+
+## Notifying on Conversion to Alumni
+
+When converting a user to an `alumni` account, a new password is set. You can use the `--notify` option to send this new password to an email address.
+
+```bash
+compiler-admin user convert some.user alumni --notify their.personal@email.com
+```

docs/guides/user/create.md

@@ -0,0 +1,37 @@
+# How to Create a New User
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user create` reference section](../../reference/cli/user.md#compiler-admin-user-create).
+
+This guide explains how to use the `compiler-admin user create` command to create a new user account in the Compiler Google Workspace.
+
+## Basic Usage
+
+To create a new user, you must provide a `username` (the part of the email address before `@compiler.la`).
+
+```bash
+compiler-admin user create new.user
+```
+
+This creates the user `new.user@compiler.la`. The command generates a random temporary password and requires the user to change it on their first login.
+
+## Notifying a Manager
+
+You can send the new user's credentials to a manager or their personal email address using the `--notify` option.
+
+```bash
+compiler-admin user create new.user --notify manager@compiler.la
+```
+
+## Passing Additional Options to GAM
+
+The `compiler-admin user create` command is a wrapper around the powerful `gam create user` command. You can pass additional arguments directly to GAM to specify more details about the user, such as their first and last name.
+
+For example, to create a user and set their name:
+
+```bash
+compiler-admin user create new.user firstname "New" lastname "User"
+```
+
+For a full list of the available options you can pass through to GAM, please refer to the [GAM7 documentation on creating users](https://github.com/GAM-team/GAM/wiki/Users#create-a-user).

docs/guides/user/deactivate.md

@@ -0,0 +1,45 @@
+# How to Deactivate a User
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user deactivate` reference section](../../reference/cli/user.md#compiler-admin-user-deactivate).
+
+This guide explains how to use the `compiler-admin user deactivate` command.
+
+This command is a major step in the offboarding process. It secures an account by revoking access, clearing personal information, and moving the user to the "Alumni" organizational unit (OU). This command is automatically called as part of the more comprehensive `user offboard` command. For most offboarding scenarios, you should use `user offboard` instead.
+
+## Actions Performed
+
+The `deactivate` command performs the following actions:
+
+- Removes the user from all of their groups.
+- Moves the user to the "Alumni" OU.
+- Resets their password to a random string.
+- Signs the user out of all active sessions.
+- Clears profile information (address, location, phone number, secondary email).
+- Resets their recovery email and phone number.
+- Turns off 2-Step Verification on their account.
+
+## Basic Usage
+
+To deactivate a user, provide their `username`.
+
+```bash
+compiler-admin user deactivate some.user
+```
+
+The command will ask for confirmation before proceeding. To bypass this, use the `--force` flag.
+
+## Setting Recovery Information
+
+You can set a new recovery email or phone number for the deactivated account using the `--recovery-email` and `--recovery-phone` options.
+
+```bash
+compiler-admin user deactivate some.user --recovery-email personal@email.com
+```
+
+To clear the recovery information, pass an empty string (which is the default):
+
+```bash
+compiler-admin user deactivate some.user --recovery-email "" --recovery-phone ""
+```

docs/guides/user/delete.md

@@ -0,0 +1,31 @@
+# How to Delete a User
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user delete` reference section](../../reference/cli/user.md#compiler-admin-user-delete).
+
+This guide explains how to use the `compiler-admin user delete` command to permanently delete a user account from the Compiler Google Workspace.
+
+**Warning:** This action is irreversible. All of the user's data that has not been transferred or backed up will be permanently lost. For a safer, more comprehensive process, use the `user offboard` command. The `offboard` command can also delete the user as its final step.
+
+## Basic Usage
+
+To delete a user, provide their `username`.
+
+```bash
+compiler-admin user delete some.user
+```
+
+The command will ask for confirmation before proceeding.
+
+## Forcing the Deletion
+
+To bypass the confirmation prompt, use the `--force` flag.
+
+```bash
+compiler-admin user delete some.user --force
+```
+
+## Important Safeguard
+
+This command will fail if the user's email address has been assigned as an alias to another account. This is a safety measure to prevent accidental deletion of an active email alias. If you intend to delete the user, you must first remove the alias from the other account.

docs/guides/user/offboard.md

@@ -0,0 +1,46 @@
+# How to Offboard a User
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user offboard` reference section](../../reference/cli/user.md#compiler-admin-user-offboard).
+
+This guide explains how to use the `compiler-admin user offboard` command to completely and securely offboard a user from the Compiler Google Workspace.
+
+This is a comprehensive command that orchestrates several other actions. For most offboarding scenarios, this is the command you should use.
+
+## Actions Performed
+
+The `offboard` command performs the following sequence of actions:
+
+1. **Deactivates the user account**: It runs all the steps from the `user deactivate` command (moves to Alumni OU, resets password, signs out, clears profile info, etc.).
+2. **Backs up email**: It creates a full backup of the user's Gmail inbox and stores it locally in a `GYB-GMail-Backup-user@compiler.la` directory.
+3. **Transfers data**: It initiates a transfer of the user's Google Drive files and Google Calendar events to the `archive@compiler.la` account.
+4. **Deprovisions access**: It deprovisions POP and IMAP access for the account.
+5. **Sets an alias (optional)**: It can assign the user's email address as an alias to another account.
+6. **Deletes the account (optional)**: It can permanently delete the user's account after all other steps are complete.
+
+## Basic Usage
+
+To offboard a user, provide their `username`.
+
+```bash
+compiler-admin user offboard departing.user
+```
+
+The command will ask for confirmation before proceeding. To bypass this, use the `--force` flag.
+
+## Assigning an Alias
+
+To forward the user's future emails to a manager or a shared inbox, use the `--alias` option.
+
+```bash
+compiler-admin user offboard departing.user --alias manager.user
+```
+
+## Deleting the Account
+
+If the account should be permanently deleted after the data is backed up and transferred, add the `--delete` flag. **Use this option with caution.**
+
+```bash
+compiler-admin user offboard departing.user --delete
+```

docs/guides/user/reactivate.md

@@ -0,0 +1,52 @@
+# How to Reactivate a User
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user reactivate` reference section](../../reference/cli/user.md#compiler-admin-user-reactivate).
+
+This guide explains how to use the `compiler-admin user reactivate` command to restore a previously deactivated user account.
+
+## Actions Performed
+
+The `reactivate` command performs the following actions:
+
+- Checks that the user is currently in the "Alumni" OU (i.e., deactivated).
+- Adds the user back to the default "Team" group.
+- Moves the user to either the "Staff" or "Contractors" OU.
+- If moved to "Staff", adds them to the "Staff" group.
+- Resets their password and requires them to change it on next login.
+- Can update their recovery email and phone number.
+- Generates a new set of 2-Step Verification backup codes and prints them to the console.
+
+## Basic Usage
+
+To reactivate a user, provide their `username`. By default, they are reactivated as a contractor.
+
+```bash
+compiler-admin user reactivate some.user
+```
+
+The command will ask for confirmation before proceeding. To bypass this, use the `--force` flag.
+
+## Reactivating as Staff
+
+To reactivate a user as a full staff member, use the `--staff` flag.
+
+```bash
+compiler-admin user reactivate some.user --staff
+```
+
+## Setting Recovery and Notification Info
+
+You can set the user's recovery information and notify them or a manager of the reactivation.
+
+- `--recovery-email`: Sets the user's recovery email address.
+- `--recovery-phone`: Sets the user's recovery phone number.
+- `--notify`: Sends the new password credentials to the specified email address.
+
+```bash
+compiler-admin user reactivate some.user \
+  --staff \
+  --recovery-email some.user.personal@email.com \
+  --notify manager@compiler.la
+```

docs/guides/user/reset.md

@@ -0,0 +1,40 @@
+# How to Reset a User's Password
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user reset` reference section](../../reference/cli/user.md#compiler-admin-user-reset).
+
+This guide explains how to use the `compiler-admin user reset` command to reset a user's password and sign them out of all sessions.
+
+## Actions Performed
+
+The `reset` command performs two main actions:
+
+1. Generates a new, random password for the user and sets the requirement that they must change it on their next login.
+2. Immediately signs the user out of all active Google sessions on all devices.
+
+## Basic Usage
+
+To reset a user's password, provide their `username`.
+
+```bash
+compiler-admin user reset some.user
+```
+
+The command will ask for confirmation before proceeding.
+
+## Forcing the Reset
+
+To bypass the confirmation prompt, use the `--force` flag.
+
+```bash
+compiler-admin user reset some.user --force
+```
+
+## Notifying the User or a Manager
+
+You can send the new temporary password to the user or their manager using the `--notify` option.
+
+```bash
+compiler-admin user reset some.user --notify manager@compiler.la
+```

docs/guides/user/restore.md

@@ -0,0 +1,30 @@
+# How to Restore an Email Backup
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user restore` reference section](../../reference/cli/user.md#compiler-admin-user-restore).
+
+This guide explains how to use the `compiler-admin user restore` command to restore a user's Gmail backup into the central `archive@compiler.la` account.
+
+This command is used to access the emails of a user who was previously offboarded using the `user offboard` command, which creates a local backup directory.
+
+## Prerequisites
+
+Before running the restore command, you must have the user's local email backup directory. This directory is created by the `user offboard` command and is named in the format `GYB-GMail-Backup-username@compiler.la`.
+
+This command must be run from the same parent directory where the backup folder is located.
+
+## Basic Usage
+
+To restore a backup for a given `username`, run the following command:
+
+```bash
+compiler-admin user restore departing.user
+```
+
+This command will:
+
+1. Locate the backup directory `GYB-GMail-Backup-departing.user@compiler.la`.
+2. Connect to the `archive@compiler.la` mailbox.
+3. Upload all emails from the backup directory into the archive mailbox.
+4. Apply a new Gmail label to all restored emails with the user's original email address (`departing.user@compiler.la`) so they can be easily found and filtered within the archive account.

docs/guides/user/signout.md

@@ -0,0 +1,29 @@
+# How to Sign a User Out of All Sessions
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin user signout` reference section](../../reference/cli/user.md#compiler-admin-user-signout).
+
+This guide explains how to use the `compiler-admin user signout` command to immediately invalidate a user's login sessions on all devices.
+
+This is useful in case a device is lost or stolen, or if an account is suspected of being compromised. This command is also called automatically as part of the `user reset` and `user deactivate` commands.
+
+## Basic Usage
+
+To sign a user out, provide their `username`.
+
+```bash
+compiler-admin user signout some.user
+```
+
+The command will ask for confirmation before proceeding.
+
+## Forcing the Signout
+
+To bypass the confirmation prompt, use the `--force` flag.
+
+```bash
+compiler-admin user signout some.user --force
+```
+
+This will immediately revoke all of the user's active Google sessions.