feat(setup): add first-time setup wizard (nylas init)

Introduce a guided onboarding experience for new CLI users. Running
`nylas` with no args now detects first-run state and shows a welcome
message pointing to `nylas init`. The wizard walks through four steps:

1. Account — register or login via SSO, or paste an existing API key
2. Application — auto-create or select from existing apps
3. API Key — generate and activate into the keyring
4. Grants — sync existing email accounts from the Nylas API

Key design decisions:
- Re-entrant: running `nylas init` again skips completed steps
- Non-interactive: `nylas init --api-key <key>` for CI/scripts
- Graceful recovery: each step prints manual commands on failure
- Shared grant sync: extracted from auth/config.go for reuse

New files: internal/cli/setup/ (detect, wizard, grants, helpers, tests)
           internal/cli/dashboard/exports.go (exported service wrappers)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AaronDDM

CLAUDE.md

@@ -106,7 +106,7 @@ Credentials stored in system keyring (service: `"nylas"`) via `nylas auth config
 
 **Quick lookup:** CLI helpers in `internal/cli/common/`, HTTP in `client.go`, Air at `internal/air/`, Chat at `internal/chat/`
 
-**CLI packages:** admin, ai, audit, auth, calendar, config, contacts, email, inbound, mcp, notetaker, otp, scheduler, slack, timezone, webhook
+**CLI packages:** admin, ai, audit, auth, calendar, config, contacts, email, inbound, mcp, notetaker, otp, scheduler, setup, slack, timezone, webhook
 
 **Additional packages:**
 - `internal/ports/output.go` - OutputWriter interface for pluggable formatting
@@ -115,6 +115,7 @@ Credentials stored in system keyring (service: `"nylas"`) via `nylas auth config
 - `internal/adapters/gpg/` - GPG/PGP email signing service (2026)
 - `internal/adapters/mime/` - RFC 3156 PGP/MIME message builder (2026)
 - `internal/chat/` - AI chat interface with local agent support (2026)
+- `internal/cli/setup/` - First-time setup wizard (`nylas init`)
 
 **Full inventory:** `docs/ARCHITECTURE.md`
 
@@ -173,6 +174,7 @@ Credentials stored in system keyring (service: `"nylas"`) via `nylas auth config
 | `make ci-full` | Complete CI (quality + tests) - **run before commits** |
 | `make ci` | Quick quality checks (no integration) |
 | `make build` | Build binary |
+| `nylas init` | First-time setup wizard |
 | `nylas air` | Start Air web UI (localhost:7365) |
 | `nylas chat` | Start AI chat interface (localhost:7367) |
 

README.md

@@ -28,13 +28,17 @@ go install github.com/nylas/cli/cmd/nylas@latest
 nylas tui --demo
 ```
 
-**Ready to connect your account?** [Get API credentials](https://dashboard.nylas.com/) (free tier available), then:
+**Ready to connect your account?** The setup wizard handles everything:
 ```bash
-nylas auth config    # Enter your API key
-nylas auth login     # Connect your email provider
+nylas init           # Guided setup — account, app, API key, done
 nylas email list     # You're ready!
 ```
 
+Already have an API key? Skip the wizard:
+```bash
+nylas init --api-key <your-key>
+```
+
 ## Basic Commands
 
 | Command | Example |

cmd/nylas/main.go

@@ -23,6 +23,7 @@ import (
 	"github.com/nylas/cli/internal/cli/notetaker"
 	"github.com/nylas/cli/internal/cli/otp"
 	"github.com/nylas/cli/internal/cli/scheduler"
+	"github.com/nylas/cli/internal/cli/setup"
 	"github.com/nylas/cli/internal/cli/slack"
 	"github.com/nylas/cli/internal/cli/timezone"
 	"github.com/nylas/cli/internal/cli/update"
@@ -45,6 +46,7 @@ func main() {
 	rootCmd.AddCommand(calendar.NewCalendarCmd())
 	rootCmd.AddCommand(contacts.NewContactsCmd())
 	rootCmd.AddCommand(dashboard.NewDashboardCmd())
+	rootCmd.AddCommand(setup.NewSetupCmd())
 	rootCmd.AddCommand(scheduler.NewSchedulerCmd())
 	rootCmd.AddCommand(admin.NewAdminCmd())
 	rootCmd.AddCommand(webhook.NewWebhookCmd())

docs/ARCHITECTURE.md

@@ -40,6 +40,7 @@ internal/
     notetaker/                # Meeting notetaker
     otp/                      # OTP extraction
     scheduler/                # Booking pages
+    setup/                    # First-time setup wizard (nylas init)
     slack/                    # Slack integration
     timezone/                 # Timezone utilities
     update/                   # Self-update

docs/COMMANDS.md

@@ -71,6 +71,25 @@ nylas completion powershell >> $PROFILE
 
 ---
 
+## Getting Started
+
+```bash
+nylas init                       # Guided first-time setup
+nylas init --api-key <key>       # Quick setup with existing API key
+nylas init --api-key <key> --region eu  # Setup with EU region
+nylas init --google              # Setup with Google SSO shortcut
+```
+
+The `init` command walks you through:
+1. Creating or logging into your Nylas account (SSO)
+2. Selecting or creating an application
+3. Generating and activating an API key
+4. Syncing existing email accounts
+
+Run `nylas init` again after partial setup — it skips completed steps.
+
+---
+
 ## Authentication
 
 ```bash

docs/DEVELOPMENT.md

@@ -70,7 +70,8 @@ internal/
   ├── domain/               # Domain models
   ├── ports/                # Interfaces
   ├── adapters/             # Implementations
-  └── cli/                  # Commands
+  ├── cli/                  # Commands (incl. setup/ for nylas init)
+  └── ...
 ```
 
 ---

docs/INDEX.md

@@ -10,6 +10,7 @@ Quick navigation guide to find the right documentation for your needs.
 
 ### Get Started
 
+- **First-time setup** → `nylas init` ([details](COMMANDS.md#getting-started))
 - **Learn about Nylas CLI** → [README.md](../README.md)
 - **Quick command reference** → [COMMANDS.md](COMMANDS.md)
 - **See examples** → [COMMANDS.md](COMMANDS.md) and [commands/](commands/)

internal/cli/auth/config.go

@@ -11,6 +11,7 @@ import (
 
 	nylasadapter "github.com/nylas/cli/internal/adapters/nylas"
 	"github.com/nylas/cli/internal/cli/common"
+	"github.com/nylas/cli/internal/cli/setup"
 	"github.com/nylas/cli/internal/domain"
 )
 
@@ -222,113 +223,53 @@ The CLI only requires your API Key - Client ID is auto-detected.`,
 			fmt.Println()
 			fmt.Println("Checking for existing grants...")
 
-			client := nylasadapter.NewHTTPClient()
-			client.SetRegion(region)
-			client.SetCredentials(clientID, "", apiKey)
-
-			ctx, cancel := common.CreateContext()
-			defer cancel()
-
-			grants, err := client.ListGrants(ctx)
+			grantStore, err := createGrantStore()
 			if err != nil {
-				_, _ = common.Yellow.Printf("  Could not fetch grants: %v\n", err)
-				fmt.Println()
-				fmt.Println("Next steps:")
-				fmt.Println("  nylas auth login    Authenticate with your email provider")
+				_, _ = common.Yellow.Printf("  Could not access grant store: %v\n", err)
 				return nil
 			}
 
-			if len(grants) == 0 {
-				fmt.Println("  No existing grants found")
+			result, err := setup.SyncGrants(grantStore, apiKey, clientID, region)
+			if err != nil {
+				_, _ = common.Yellow.Printf("  Could not fetch grants: %v\n", err)
 				fmt.Println()
 				fmt.Println("Next steps:")
 				fmt.Println("  nylas auth login    Authenticate with your email provider")
 				return nil
 			}
 
-			// Get grant store to save grants locally
-			grantStore, err := createGrantStore()
-			if err != nil {
-				_, _ = common.Yellow.Printf("  Could not save grants locally: %v\n", err)
-				return nil
-			}
-
-			// First pass: Add all valid grants without setting default
-			var validGrants []domain.Grant
-			for _, grant := range grants {
-				if !grant.IsValid() {
-					continue
-				}
-
-				grantInfo := domain.GrantInfo{
-					ID:       grant.ID,
-					Email:    grant.Email,
-					Provider: grant.Provider,
-				}
-
-				if err := grantStore.SaveGrant(grantInfo); err != nil {
-					continue
-				}
-
-				validGrants = append(validGrants, grant)
-				_, _ = common.Green.Printf("  ✓ Added %s (%s)\n", grant.Email, grant.Provider.DisplayName())
-			}
-
-			if len(validGrants) == 0 {
+			if len(result.ValidGrants) == 0 {
 				fmt.Println("  No valid grants found")
 				fmt.Println()
 				fmt.Println("Next steps:")
 				fmt.Println("  nylas auth login    Authenticate with your email provider")
 				return nil
 			}
 
-			// Second pass: Set default grant
-			var defaultGrantID string
-			if len(validGrants) == 1 {
-				// Single grant - auto-select as default
-				defaultGrantID = validGrants[0].ID
-				_ = grantStore.SetDefaultGrant(defaultGrantID)
+			// Set default grant
+			defaultGrantID := result.DefaultGrantID
+			if defaultGrantID != "" {
+				// Single grant, auto-selected
 				fmt.Println()
-				_, _ = common.Green.Printf("✓ Set %s as default account\n", validGrants[0].Email)
-			} else {
-				// Multiple grants - let user choose default
-				fmt.Println()
-				fmt.Println("Select default account:")
-				for i, grant := range validGrants {
-					fmt.Printf("  [%d] %s (%s)\n", i+1, grant.Email, grant.Provider.DisplayName())
-				}
-				fmt.Println()
-				fmt.Print("Select default account (1-", len(validGrants), "): ")
-				input, _ := reader.ReadString('\n')
-				choice := strings.TrimSpace(input)
-
-				var selected int
-				if _, err := fmt.Sscanf(choice, "%d", &selected); err != nil || selected < 1 || selected > len(validGrants) {
-					// If invalid selection, default to first
-					_, _ = common.Yellow.Printf("Invalid selection, defaulting to %s\n", validGrants[0].Email)
-					defaultGrantID = validGrants[0].ID
-				} else {
-					defaultGrantID = validGrants[selected-1].ID
-				}
-
-				_ = grantStore.SetDefaultGrant(defaultGrantID)
-				selectedGrant := validGrants[0]
-				for _, g := range validGrants {
+				_, _ = common.Green.Printf("✓ Set %s as default account\n", result.ValidGrants[0].Email)
+			} else if len(result.ValidGrants) > 1 {
+				// Multiple grants, prompt
+				defaultGrantID, _ = setup.PromptDefaultGrant(grantStore, result.ValidGrants)
+				for _, g := range result.ValidGrants {
 					if g.ID == defaultGrantID {
-						selectedGrant = g
+						_, _ = common.Green.Printf("✓ Set %s as default account\n", g.Email)
 						break
 					}
 				}
-				_, _ = common.Green.Printf("✓ Set %s as default account\n", selectedGrant.Email)
 			}
 
 			fmt.Println()
-			fmt.Printf("Added %d grant(s). Run 'nylas auth list' to see all accounts.\n", len(validGrants))
+			fmt.Printf("Added %d grant(s). Run 'nylas auth list' to see all accounts.\n", len(result.ValidGrants))
 
 			// Update config file with default grant and grants list
 			cfg.DefaultGrant = defaultGrantID
-			cfg.Grants = make([]domain.GrantInfo, len(validGrants))
-			for i, grant := range validGrants {
+			cfg.Grants = make([]domain.GrantInfo, len(result.ValidGrants))
+			for i, grant := range result.ValidGrants {
 				cfg.Grants[i] = domain.GrantInfo{
 					ID:       grant.ID,
 					Email:    grant.Email,

internal/cli/dashboard/exports.go

@@ -0,0 +1,41 @@
+package dashboard
+
+import (
+	dashboardapp "github.com/nylas/cli/internal/app/dashboard"
+	"github.com/nylas/cli/internal/ports"
+)
+
+// CreateAuthService creates the dashboard auth service chain (exported for setup wizard).
+func CreateAuthService() (*dashboardapp.AuthService, ports.SecretStore, error) {
+	return createAuthService()
+}
+
+// CreateAppService creates the dashboard app management service (exported for setup wizard).
+func CreateAppService() (*dashboardapp.AppService, error) {
+	return createAppService()
+}
+
+// RunSSO executes the SSO device-code flow (exported for setup wizard).
+func RunSSO(provider, mode string, privacyAccepted bool) error {
+	return runSSO(provider, mode, privacyAccepted)
+}
+
+// AcceptPrivacyPolicy prompts for privacy policy acceptance (exported for setup wizard).
+func AcceptPrivacyPolicy() error {
+	return acceptPrivacyPolicy()
+}
+
+// ActivateAPIKey stores an API key in the keyring and configures the CLI (exported for setup wizard).
+func ActivateAPIKey(apiKey, clientID, region string) error {
+	return activateAPIKey(apiKey, clientID, region)
+}
+
+// GetActiveOrgID retrieves the active organization ID (exported for setup wizard).
+func GetActiveOrgID() (string, error) {
+	return getActiveOrgID()
+}
+
+// ReadLine prompts for a line of text input (exported for setup wizard).
+func ReadLine(prompt string) (string, error) {
+	return readLine(prompt)
+}

internal/cli/dashboard/register.go

@@ -56,4 +56,3 @@ func runSSORegister(provider string) error {
 	}
 	return runSSO(provider, "register", true)
 }
-