Shepherd Onboard

Customer-facing raw sync onboarding for Shepherd.

Coding Agent One-liner

Give this to a coding agent:

npx -y shepherd-onboard@latest agent

The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync. The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs messages-chats, opens a minimal searchable local webpage, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth. Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.

Human Terminal One-liner

npx -y shepherd-onboard@latest

The command:

• runs Shepherd WorkOS login/signup first
• asks for name, organization, and an optional local Messages handle
• creates or reuses the Shepherd customer account from the WorkOS-authenticated email
• creates or reuses the organization, including case-insensitive and close-name matches
• only reuses an existing organization when the authenticated account is allowed to join it
• prints Google Workspace domain-wide delegation setup for a Workspace super admin
• opens Slack authorization
• opens the Granola desktop app to Settings -> Connectors -> API keys
• collects the Granola API key after opening the Granola screen when Granola is enabled
• asks the user to grant or confirm macOS Full Disk Access before local Messages sync
• checks local Messages access and keeps prompting in interactive onboarding until Full Disk Access works
• opens a minimal searchable local webpage with contact/group names and only syncs the chats selected by the user
• sets up local macOS Messages raw sync with a background LaunchAgent scoped to the selected chats
• starts raw polling/backfill for connected sources
• does not start wiki generation, memory compilation, or doc summaries

The command does not expose Railway, database, Redis, or internal service details to the user.

Google Workspace Domain-wide Delegation

Business customers connect Google Workspace once as an admin. Employees do not create service accounts and do not each complete Google OAuth for Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, or Contacts.

Customer-side setup in Google Admin Console:

App name: Shepherd
Service account email: [email protected]
Domain-wide delegation OAuth Client ID: 118363960386741325727

The customer super admin authorizes that Client ID with the scopes printed by the CLI. The customer does not upload service account JSON; Shepherd stores its private service account JSON server-side in GOOGLE_WORKSPACE_SERVICE_ACCOUNT_KEY_JSON and requests delegated tokens with sub=<allowed_employee_email>.

Shepherd must still enforce selected users and groups internally before impersonating or polling employee emails.

Options

--email <email>            Advanced: must match the WorkOS-authenticated email
--name <name>              Full name
--org <name>               Organization name
--granola-api-key <key>    Granola API key
--messages-handle <value>  Messages phone number or Apple ID email
--messages-chat-ids <ids>  Comma-separated chat IDs selected from messages-chats
--messages-backfill-days   Local Messages backfill window, default all selected chat history
--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)
--no-slack                 Skip Slack
--no-granola               Skip Granola
--no-open-granola          Do not open the Granola API key screen
--no-messages              Skip local Messages
--no-open                  Print auth URLs instead of opening the browser

Messages Chat Selection

Local Messages sync on macOS needs Full Disk Access. During onboarding, Shepherd asks the user to grant or confirm Full Disk Access for:

• the app running onboarding, such as Terminal, iTerm, Claude Code, or Codex
• the Node.js binary used by the background LaunchAgent

The Messages selector validates access to ~/Library/Messages/chat.db, opens System Settings -> Privacy & Security -> Full Disk Access if access is missing, and keeps checking in interactive onboarding until access works. Background sync install also checks that launchd can start the Messages agent. Contacts permission may also appear when Shepherd resolves local contact names for selected chats.

Open the local Messages chat selector:

npx -y shepherd-onboard@latest messages-chats

Use --json for machine-readable chat metadata, or --text for a terminal list.

The browser selector displays the first page of recent chats and lets the user search contacts or groups loaded from local Messages.

Pass the selected chat IDs when finishing onboarding:

npx -y shepherd-onboard@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"

Granola API Keys

If Granola does not land on the API keys page, run:

npx -y shepherd-onboard@latest granola-api-keys