AskShepherd Support CLI

Support/developer CLI for Shepherd production onboarding and MCP. Normal customers should use the Shepherd macOS app; the app bundles this same engine and installs background sync/MCP without asking customers to run npx.

The npm package is askshepherd. The installed binary also exposes shepherd, and the support CLI uses the package name:

claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets>." --dangerously-skip-permissions

Claude Code Onboarding Command

Give this to Claude Code:

claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets>." --dangerously-skip-permissions

The underlying askshepherd agent command defaults to the customer-facing production Shepherd cloud. In coding-agent shells, it gives the agent the public onboarding checklist and follow-up commands. In a normal interactive terminal, it does not print the checklist; it points the user to the direct terminal onboarding flow instead. Claude Code onboarding asks short selection questions first: existing/new org, sources to connect, Messages skip/provide-handle, and whether to sync Coding Sessions from Codex/Claude Code. 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. If Coding Sessions is selected, onboarding installs a local LaunchAgent that syncs redacted session summaries, not full raw transcripts. Account creation/relinking always starts with Shepherd WorkOS auth. After onboarding completes, the agent asks whether to install Shepherd MCP for the signed-in customer into Codex, Claude Code, Cursor, any subset, or none. Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.

For experiments, pass a separate non-production API explicitly:

claude "Run Shepherd customer onboarding with: npx -y askshepherd@latest agent --api https://<non-prod-brain-api>. Ask me the onboarding questions, do not infer answers from local context, and continue through the follow-up commands it prints. After onboarding completes, ask whether to install Shepherd MCP for me into Codex, Claude Code, Cursor, any subset, or none; if I choose any, run npx -y askshepherd@latest mcp-login --install <targets> --api https://<non-prod-brain-api>." --dangerously-skip-permissions

Human Terminal One-liner

npx -y askshepherd@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, including contact-name hydration for observed conversations
• optionally sets up local Codex/Claude Code coding-session summary sync with a background LaunchAgent
• starts raw polling/backfill for connected sources
• asks the customer-facing production cloud to schedule downstream processing; wiki ingestion, memory artifacts, and document summaries run in separate brain services, not in the local CLI

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

Check Sync Status

Use this when the user asks "Check what I've enabled for Shepherd?":

npx -y askshepherd@latest status
npx -y askshepherd@latest status --json

It reports the saved Shepherd account, connected cloud sources, downstream processing state, and local background sync health for Messages and Coding Sessions.

Agents must not inspect the user's folders or repositories to answer setup status. Do not run ls, find, rg, grep, cat, Read, Glob, or Explore against the user's home directory, repositories, ~/.codex, ~/.claude, or ~/.shepherd for Shepherd setup. Use the npm status command above; it performs the bounded local checks.

Set Up Coding Agent Sessions

Use this when the user asks "Help me set up coding agent sessions" or "Enable coding agent sessions locally for Shepherd":

npx -y askshepherd@latest agent --login
npx -y askshepherd@latest agent --add-sources coding-sessions --name "<name>" --org "<organization>"
npx -y askshepherd@latest agent --continue
npx -y askshepherd@latest status

The coding agent should ask for consent before enabling this source. The local collector syncs redacted Codex and Claude Code summaries, not full transcripts. The agent should run only the commands above and should not search the local filesystem for a Shepherd agent implementation.

Customer MCP Login

After raw onboarding creates the Shepherd customer account, customers can install the production MCP from the saved local onboarding session:

npx -y askshepherd@latest mcp-login

The command first verifies ~/.shepherd/raw-onboarding-agent.json against the production API and mints an MCP token for that exact customer account. If the local onboarding session is unavailable, it falls back to Shepherd WorkOS auth and still links only an existing onboarded customer account. It writes ~/.shepherd/mcp.json and asks where Shepherd MCP should be accessible. It can install the MCP into:

• Codex CLI/app
• Claude Code
• Cursor IDE and Cursor Agent

The saved MCP state includes:

• mcpUrl: https://brain-api-customer-facing.up.railway.app/mcp
• token: bearer token for MCP clients
• account: linked customer account metadata
• authSource: local_onboarding or workos
• localAuth: raw onboarding state reference when local auth was used

The installed MCP server is local npm first, remote brain second. For questions like "what do I have set up on Shepherd?", "is Shepherd syncing?", or "help me set up coding agent sessions", the MCP exposes local tools such as shepherd_status, shepherd_setup_coding_sessions, and shepherd_enable_coding_sessions that route agents to the local askshepherd status / add-source flow. Production memory and wiki tools remain remote Railway-backed tools for source recall and company-memory answers. Those local MCP tools are also the permission boundary: an MCP client should not use shell or file tools to inspect the user's folders or repositories for setup.

Use --json when an agent or setup script needs machine-readable endpoint and header details.

Install an existing MCP login later:

npx -y askshepherd@latest mcp-install

mcp-install refreshes missing or near-expired MCP auth from the saved local onboarding session before configuring clients, so already-onboarded customers do not need to sign in again. Local Messages continues syncing through its LaunchAgent and cloud sources continue syncing through production pollers; MCP auth only controls read access to that customer's production memory/wiki data.

Install targets can also be provided non-interactively:

npx -y askshepherd@latest mcp-login --install codex,claude,cursor
npx -y askshepherd@latest mcp-install --install all

After install, customers can immediately ask their coding agent questions like:

Use Shepherd to catch me up on what the team discussed yesterday.
Use Shepherd to search Slack, Gmail, Messages, Granola, and the wiki for launch blockers.
Use Shepherd to find the last meeting where we discussed the enterprise pilot.
Use Shepherd to summarize open follow-ups from this week's memory.
Use Shepherd to tell me what coding agents already worked on in this repo.

The production MCP gives onboarded customers the same read/QA behavior that made the internal Shepherd MCP useful: summary-first answers, wiki search/read, and source drill-in. Internal local sync, admin, replay, write/delete, and cache maintenance tools are not exposed to customers.

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, or `all` to watch every current and future chat
--messages-backfill-days   Local Messages backfill window, default all selected chat history
--api <url>                Advanced: Shepherd API URL. Use only for non-production experiments or local/staging testing.
--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
--coding-sessions          Opt in to local Codex/Claude Code session summary sync
--sources <list>           Exact sources to connect: google,slack,granola,messages,coding-sessions,all
--add-sources <list>       Same as --sources, named for second-time onboarding
--no-open                  Print auth URLs instead of opening the browser

Coding Sessions

Customers can add coding-session sync during first onboarding by selecting Coding Sessions or by passing:

npx -y askshepherd@latest agent --sources coding-sessions --name "<name>" --org "<organization>"

Already-onboarded customers can add it later:

npx -y askshepherd@latest agent --add-sources coding-sessions --name "<name>" --org "<organization>"

The local collector reads Codex session JSONL under ~/.codex/sessions and Claude Code JSONL under ~/.claude/projects, redacts sensitive values locally, and uploads bounded summaries with repo, command, file, verification, and follow-up metadata. It does not upload full raw transcripts. In production, Shepherd writes a concise building/index.md recent-work ledger plus detailed session pages under coding-sessions/ for MCP drill-in.

Check local and production sync health:

npx -y askshepherd@latest coding-sessions-status
npx -y askshepherd@latest coding-sessions-status --json

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. The background agent reloads Contacts on startup, watches AddressBook changes when available, and runs a periodic fallback sync so renamed contacts can hydrate prior ingested Messages rows for that customer account.

Open the local Messages chat selector:

npx -y askshepherd@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. It also has an explicit "Sync all current and future chats" option for users who want Shepherd to backfill every current local Messages chat and keep watching chats that appear later. Do not use this option by default; it is for explicit user approval.

Pass the selected chat IDs when finishing onboarding:

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

Or, with explicit approval to sync all local Messages chats:

npx -y askshepherd@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids all

Granola API Keys

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

npx -y askshepherd@latest granola-api-keys