From b195d42b7381919348d1b0bd5f9bc1ec1b71ca74 Mon Sep 17 00:00:00 2001
From: Oliver Mannion <125105+tekumara@users.noreply.github.com>
Date: Sun, 9 Jun 2024 21:38:38 +1000
Subject: [PATCH] docs: comparison with github cli

---
 README.md   | 10 ++++++++++
 cmd/root.go |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4fc661e..e3af0ac 100644
--- a/README.md
+++ b/README.md
@@ -118,3 +118,13 @@ Global Flags:
 If your organisation uses SAML single sign-on [authorize your SSH key](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on) for use with the organisation.
 
 By default [access via third-party applications](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) to organisation resources is restricted. Request the gh-doctor OAuth app be [approved for use in your organisation](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps).
+
+## FAQ
+
+### How does GitHub Doctor compare to the GitHub CLI?
+
+The GitHub CLI (gh) can [add an existing ssh key](https://cli.github.com/manual/gh_ssh-key_add) to your account. However:
+
+- gh is less secure. GitHub can only generate [long-lived OAuth tokens](https://github.com/cli/cli/issues/5924). gh persists these in the keychain, but `gh auth token` will [return the token in plaintext](https://github.com/cli/cli/issues/8237) bypassing any keychain security. Whilst gh-doctor must also use long-lived OAuth tokens, they don't leave memory and are never persisted.
+- gh doesn't modify your ssh config, or load the key into the agent as per the [GitHub docs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+- gh doesn't diagnose and fix misconfigurations. Nor does it run idempotently.
diff --git a/cmd/root.go b/cmd/root.go
index eb10bc0..c4a758c 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -11,7 +11,7 @@ import (
 var rootCmd = &cobra.Command{
 	Use:   "gh-doctor",
 	Short: "Set up ssh and gh auth tokens.",
-	Long: `Github Doctor
+	Long: `GitHub Doctor
 
 Set up ssh and gh auth tokens.