nixcache: improve sudo prompt and help docs (#2107)

Author: gcurtis

internal/boxcli/cache.go

@@ -80,8 +80,23 @@ func cacheCmd() *cobra.Command {
 func cacheConfigureCmd() *cobra.Command {
 	username := ""
 	cmd := &cobra.Command{
-		Use:    "configure",
-		Short:  "Configure Nix to use the Devbox cache as a substituter",
+		Use:   "configure",
+		Short: "Configure Nix to use the Devbox cache as a substituter",
+		Long: heredoc.Doc(`
+			Configure Nix to use the Devbox cache as a substituter.
+
+			If the current Nix installation is multi-user, this command grants the Nix
+			daemon access to Devbox caches by making the following changes:
+
+			- Adds the current user to Nix's list of trusted users in the system nix.conf.
+			- Adds the cache credentials to ~root/.aws/config.
+
+			Configuration requires sudo, but only needs to happen once. The changes persist
+			across Devbox accounts and organizations.
+
+			This command is a no-op for single-user Nix installs that aren't running the
+			Nix daemon.
+		`),
 		Hidden: true,
 		Args:   cobra.MaximumNArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) error {

internal/devbox/providers/nixcache/setup.go

@@ -38,22 +38,28 @@ func Configure(ctx context.Context) error {
 	if err != nil {
 		return redact.Errorf("nixcache: lookup current user: %v", err)
 	}
-	return configure(ctx, u.Username, false)
-}
 
-func ConfigureReprompt(ctx context.Context, username string) error {
-	return configure(ctx, username, true)
-}
+	task := &setupTask{u.Username}
 
-func configure(ctx context.Context, username string, reprompt bool) error {
-	if reprompt {
-		setup.Reset(setupKey)
+	// This function might be called from other Devbox commands
+	// (such as devbox add), so we need to provide some context in the sudo
+	// prompt.
+	const sudoPrompt = "You're logged into a Devbox account, but Nix isn't setup to use your account's caches. " +
+		"Allow sudo to configure Nix?"
+	err = setup.ConfirmRun(ctx, setupKey, task, sudoPrompt)
+	if err != nil {
+		return redact.Errorf("nixcache: run setup: %w", err)
 	}
+	return nil
+}
 
+func ConfigureReprompt(ctx context.Context, username string) error {
+	setup.Reset(setupKey)
 	task := &setupTask{username}
-	const sudoPrompt = "You're logged into a Devbox account that now has access to a Nix cache. " +
-		"Allow Devbox to configure Nix to use the new cache (requires sudo)?"
-	err := setup.ConfirmRun(ctx, setupKey, task, sudoPrompt)
+
+	// We're reprompting, so the user explicitly asked to configure the
+	// cache. We can keep the sudo prompt short.
+	err := setup.ConfirmRun(ctx, setupKey, task, "Allow sudo to configure Nix?")
 	if err != nil {
 		return redact.Errorf("nixcache: run setup: %w", err)
 	}