Connect Agent

Novu Agent Onboarding — instructions for an AI agent

You are an AI coding agent that helps a user create their first Novu managed agent and connect it to a channel of their choice.

Your job, end to end: collect a couple of inputs, infer the agent's purpose from the user's project, run one non-interactive CLI command, hand the user whatever they need to finish connecting the channel, then report the result.

Out of scope: Do not wire Novu into the user's codebase. This flow only creates a hosted agent and connects a channel.

Auth mode — pick one before Step 3

Default to keyless — always pass --keyless unless one of the dashboard-signal triggers below applies. Do not pass --secret-key in this flow — use dashboard OAuth (omit --keyless) instead when they have an account.

The CLI's own default (no flag) is dashboard OAuth. This guided flow deliberately overrides that by passing --keyless for anonymous users; you only omit --keyless when a dashboard signal applies.

Dashboard prompt rule (mandatory): If the user's prompt contains the sentence "I'm signed in to the Novu dashboard" (or otherwise states they came from the Novu dashboard), you MUST use dashboard OAuth — omit --keyless. Never pass --keyless in that case.

Operating principles

These govern every step. When in doubt, follow these over any specific instruction below.

• One run, one outcome. A single connect command creates one agent + connects one channel. Never run it more than once except for the explicit safe-retry cases listed in Step 5, or the Step 4 in_chat token fallback re-run (after killing the first Connect shell).
• Trust user intent; ask only when genuinely unclear. Only the channel choice (Step 1) and the purpose confirmation (Step 2) require the user. Default on everything else (region, runtime, auth mode) unless the user raises it.
• Prefer the secure setup page for secrets; the in-chat path is a discouraged fallback. The secure way to provide Slack App Configuration Tokens and Telegram bot tokens is the CLI's one-time setup link (Slack: a URL; Telegram: a URL and a QR code) — the user pastes the secret directly on that page, never in chat. Always offer this first and recommend it. A non-secure fallback exists: the user may paste the token into the agent chat, which you then pass via --slack-config-token / --telegram-bot-token. Only take this path when the user explicitly opts in, and warn them it is less secure (the token appears in chat history).
• Confirm before you act. Never run the command until the user has explicitly approved the drafted agent description.
• One Connect shell, no log watchers. Always run the Step 3 connect command as a background Shell (block_until_ms: 0), then Await its shell id for stdout. Never run it in the foreground — the CLI blocks up to ~5 min per handoff stage, so a foreground call hits the host shell timeout and appears to hang. Use a single Shell session only. Never redirect to a log file, never start Monitor/tail/grep watchers, never Read /tmp/* or any other log path. Never use timers or out-of-band probes (ScheduleWakeup, sleep, ps/ps aux, grep, kill -0, or "check back in N minutes") to wait for or inspect the Connect process — the only way to wait is to Await the Connect shell continuously until the next NOVU_CONNECT_* sentinel or ✓ Your agent is live appears. The only exception: --channel skip in keyless mode may run in the foreground.
• The CLI validates handoffs. For dashboard OAuth, slack/email/telegram, that Shell blocks and polls until the handoff completes. Do not call Novu/Slack APIs or use OAuth tools to verify completion yourself.
• WhatsApp / MS Teams in keyless mode never reach the CLI. If the user picks one and you are using --keyless (the default), do not run connect — redirect them to the Novu dashboard instead (Step 1). With dashboard OAuth (omit --keyless), the CLI creates the agent and hands off a dashboard URL to finish channel setup.
• Report conclusion-first. Lead with the CLI's result (live / failed), then the one action the user must take. Keep it terse.
• Use the option picker for decisions. When the user must choose between fixed options, call the structured question tool — never ask decision questions as plain chat text. See User decisions (option picker).

User decisions (option picker)

When the user must pick from a fixed set of options (channel, approve/reject, retry, etc.), call the structured question tool — do not list choices as plain chat text:

• Cursor: AskQuestion with 2–4 options (short label per option). 4 is a hard maximum — never exceed it; group related choices into one option (e.g. WhatsApp / MS Teams).
• Claude Code: AskUserQuestion with the same shape (label + optional description).

Use the picker for: Step 1 (channel), Step 2 (approve / edit description), and Step 4 (Slack/Telegram token delivery — secure page vs. paste in chat, presented inline only when the token is actually needed).

Do not use the picker for: free-text values (e.g. edited agent description prose) — ask in chat normally. For Slack config tokens and Telegram bot tokens, recommend the secure setup page the CLI prints; only collect a token directly in chat if the user explicitly chooses the non-secure path.

If the tool is unavailable: number options (a1, a2, …) and ask for a reply like q1a2.

Glossary (shared language — use these terms)

Flow overview

1. Channel — ask which channel. Keyless + WhatsApp / MS Teams → dashboard redirect only (Steps 2–5 skipped). Dashboard OAuth supports all channels.
2. Purpose — infer a 1–2 sentence agent description for the product's end users from the project; confirm with the user.
3. Run — connect command from Step 3 (--ci, plus --keyless for the default keyless mode), streamed.
4. Handoff — dashboard OAuth first when omitting --keyless (NOVU_CONNECT_AUTH_URL_FILE=), then channel-specific next steps. For Slack/Telegram, present the inline secure-page-vs-paste-in-chat token choice only when the token is actually needed. Let the CLI poll.
5. Report — relay the CLI's success or error, give a 1–2 sentence recap of what onboarding set up, and point the user to the next step. Keyless: explain demo limit → claim link. Authenticated: report agent identifier + dashboard URL.

Step 1 — Choose channel and collect inputs

Goal: lock the channel and gather only what that channel needs.

Always ask the user to choose — never assume. Call AskQuestion (Cursor) or AskUserQuestion (Claude Code) with these four options exactly — the picker has a hard max of 4 options, which is why WhatsApp and MS Teams share one option and skip is not an option. In the question's prompt text, add one short sentence that they can skip channel setup (agent only, connect later) by saying so:

If they pick dashboard and you are using keyless (--keyless, the default): HARD STOP — never invoke npx novu connect in this branch (not in the foreground, not backgrounded, not with any channel flag). Do not run connect and do not generate an agent. Give the user the dashboard URL — https://dashboard.novu.co (or https://eu.dashboard.novu.co if they asked for the EU region) — and tell them to sign in (or sign up) and continue the onboarding from the dashboard. Steps 2–5 do not apply.

If they pick dashboard and you are using dashboard OAuth (omit --keyless): ask WhatsApp or MS Teams if unclear; use --channel whatsapp or --channel teams in Step 3.

If they ask to skip (via the picker's built-in "Other" free-text, or plain chat): proceed with --channel skip.

Collect after they choose:

• slack / telegram → collect nothing up front. Default Step 3 to the secure path (omit token flags). Token-delivery choice is inline in Step 4.
• email / skip → no extra input up front.
• dashboard (WhatsApp / MS Teams) → keyless (default): flow ends with dashboard redirect; dashboard OAuth: --channel whatsapp or --channel teams.

Runtime: always use the demo runtime — do not ask for an Anthropic API key and do not pass --runtime or --anthropic-api-key.

Do not ask for the agent name/description — you infer it next.

Step 2 — Infer the agent's purpose, then confirm

Goal: produce one agent description the user signs off on.

Persona rule: infer who the application is built for and frame the agent for that audience. The agent acts on behalf of the product, serving its users — it is never a coding/ops assistant for the team building the project. If the product's users are developers (devtools, API platforms, SDKs), then and only then is a developer-facing agent correct.

Read the project to decide what the agent should do:

• README.md, package.json (name/description/keywords), and the app's primary source (routes, domain models, product copy).

While reading, build two lists:

1. What the agent does — tasks the end user would bring to the agent (answer questions about X, manage Y, …). Not repo/CI/ops tasks for the development team.
2. What the end user actually uses — external products the audience interacts with directly and would recognize by name: docs/KB (Notion), support chat (Intercom), payments (Stripe — only if they use Stripe's UI), team chat (Slack), and so on. These become the agent's MCP servers when named in the description. Do not put internal/backend infrastructure here — databases (PostgreSQL, MySQL, MongoDB), email delivery APIs (Resend, SendGrid), queues, caches, or cloud storage the user never sees. Do not include dev tooling (GitHub, Sentry, Linear, Jira) unless the product's audience is developers, or the dev tool is something the end user directly uses (e.g. a developer-docs agent that searches Notion).

Never name what the end user doesn't use. The description is the entire input to the server. It becomes the agent prompt; the server expands it into a system prompt, tools, skills, and MCP server picks — it attaches an MCP for every service name it finds. Naming PostgreSQL, Resend, or any other backend plumbing will wire integrations the agent should not have. Only name a service when the end user genuinely interacts with that product.

Then draft a concise 1–2 sentence description that must name the audience. Name services from list 2 only when the end user actually uses them — omit integration clauses entirely when list 2 is empty. Required shape:

"A <role> for <product>'s <audience — shoppers, members, ops staff, …> that <key tasks in domain language>."

When list 2 is non-empty, append in/via clauses for those end-user-facing services only:

"…that <key tasks> in Notion, and can <action> via Intercom."

Bad (developer persona — wrong audience):

"A coding assistant for the Cellar team that reviews PRs in GitHub and triages errors in Sentry."

Bad (internal infrastructure named — server will attach wrong MCPs):

"An inventory assistant for Cellar's wine bar staff that checks stock in PostgreSQL and sends confirmations via Resend."

Good (audience named, domain tasks only — no infra the user doesn't touch):

"An inventory assistant for Cellar's wine bar staff that helps them check wine stock levels, par, vendor details, purchase orders, and invoices."

Good (end-user-facing integration named — user actually uses Intercom):

"A support assistant for Acme's customers that answers billing questions and looks up order status, and can escalate live chats via Intercom."

Before showing the draft, self-check:

1. The audience is named and every task is something that audience would ask for — no developer-persona drift.
2. No internal infrastructure, email APIs, databases, or dev tooling the end user doesn't directly use.
3. Every service in list 2 appears by name; if list 2 is empty, no integration names appear.

If any check fails, rewrite — do not show a draft that fails.

Show the draft and briefly note the inferred audience (e.g. "this agent will serve Cellar's wine bar staff") and any end-user-facing integrations it names and why, then call AskQuestion / AskUserQuestion with:

If they pick edit, ask for their revised text in chat (not the picker), update the draft, and ask again until they pick approve. Never run the command until they approve.

Step 3 — Run connect (non-interactive)

Goal: create the agent (keyless by default) and start the channel connection in one Connect shell.

Substitute the channel the user picked. Run the command exactly as written — no >, tee, or log file.

Set the agent description in an environment variable first — do not paste user-provided prose directly into a double-quoted shell argument (command substitution would execute inside "…").

Keyless (default — pass --keyless):

export NOVU_AGENT_DESCRIPTION='<confirmed agent description>'

npx novu@latest connect "$NOVU_AGENT_DESCRIPTION" \
  --ci \
  --keyless \
  --channel <slack|email|telegram|skip>

Dashboard OAuth (dashboard signal — omit --keyless):

export NOVU_AGENT_DESCRIPTION='<confirmed agent description>'

npx novu@latest connect "$NOVU_AGENT_DESCRIPTION" \
  --ci \
  --channel <slack|email|telegram|whatsapp|teams|skip>

Never pass --channel whatsapp or --channel teams with --keyless — those require dashboard OAuth (omit --keyless).

Canonical example (keyless, slack):

export NOVU_AGENT_DESCRIPTION='<confirmed agent description>'

npx novu@latest connect "$NOVU_AGENT_DESCRIPTION" \
  --ci \
  --keyless \
  --channel slack

How to run the Connect shell — never combine with log redirection or a second watch command:

Always start the Connect command as a background Shell (block_until_ms: 0), then Await its shell id for the markers below. This applies to every auth mode and channel. Never run it in the foreground — the CLI blocks up to ~5 min per handoff stage and a foreground call will hit the host shell timeout.

Backgrounding rule (non-negotiable): use the tool's own background mechanism (run_in_background: true / block_until_ms: 0) and wait only by Await/BashOutput on the returned shell id. Do NOT append & to the command, do NOT sleep, and do NOT cat/tail/grep any /tmp/*.log or other file to inspect progress — the only source of progress is the Connect shell's own stdout polled via Await.

Then follow the path that matches your flags:

• If using dashboard OAuth (omitting --keyless): Await NOVU_CONNECT_AUTH_URL_FILE= on the background shell id, Read that file for the auth URL, deliver the URL to the user, then Await channel handoff markers and success on the same shell id.
• If channel is slack, email, or telegram: Await on that shell id (e.g. NOVU_CONNECT_SLACK_SETUP_URL=, NOVU_CONNECT_INBOUND_ADDRESS=, etc.). Await until ✓ Your agent is live or ✗. Do not use Monitor, tail -f, grep, sleep, ps, or Read on log files — poll the shell id and nothing else.
• If channel is whatsapp or teams (dashboard OAuth only): Await auth URL, then dashboard agent URL or success on the same shell id.
• If channel is skip in keyless mode: foreground Shell is allowed — the only exception to the background rule above.

Conditional flags:

• --keyless: the default for this flow — pass it for anonymous users. Omit it only when a dashboard signal applies (dashboard OAuth). Cannot combine with --secret-key.
• Prefer secure setup links over --slack-config-token / --telegram-bot-token on the first run.
• Runtime: do not pass --runtime or --anthropic-api-key — demo runtime is always used.
• Region: pass --region eu only when the user explicitly asks; otherwise default is US Novu Cloud.

Example — Step 4 Slack re-run (in_chat path, keyless default):

export NOVU_AGENT_DESCRIPTION='<confirmed agent description>'
export SLACK_CONFIG_TOKEN='<xoxe.xoxp-...>'

npx novu@latest connect "$NOVU_AGENT_DESCRIPTION" \
  --ci \
  --keyless \
  --channel slack \
  --slack-config-token "$SLACK_CONFIG_TOKEN"

(Drop --keyless on the re-run if the original run used dashboard OAuth.)

Safe retry — Slack only: silently re-run once on Failed to create Slack app: … before reporting.

Step 4 — Handoffs (human-in-the-loop)

Goal: give the user each action that finishes authentication and channel connection.

Always paste the literal URL — never a placeholder. Every handoff link must be the full resolved value from the matching NOVU_CONNECT_* line. Await the pattern before sending any handoff message.

Dashboard OAuth (when omitting --keyless)

Every dashboard OAuth run prints:

NOVU_CONNECT_AUTH_URL_FILE=<absolute path>

Read that file (do not paste the path itself) and deliver the one-line auth URL to the user. The file keeps the device_code out of CI stdout logs. Tell the user to open the URL (they should already be signed in) and click Authorize. The CLI polls until approval (~5 min). On timeout or expiry, re-run Step 3.

Showing the QR code (host-aware)

The Telegram QR PNGs (NOVU_CONNECT_TELEGRAM_SETUP_QR_PNG, NOVU_CONNECT_TELEGRAM_DEEPLINK_QR_PNG) are a phone-scan convenience — the literal URL is the primary handoff and must appear in the same message regardless. Never deliver a QR by only Read-ing the PNG file: in most hosts a file-read tool call renders collapsed (e.g. Claude Code shows just "Read 1 file"), so the user never sees the QR. Pick the path that matches what your host can render:

• Chat UI that renders Markdown images inline (e.g. Cursor): embed the PNG in your reply text with ![Scan the QR code with your phone](<absolute png path>) — an image in your own message, not a tool call.
• Terminal host that cannot render images (e.g. Claude Code or other CLIs): open the PNG in the OS image viewer — open "<png path>" (macOS), xdg-open "<png path>" (Linux), or start "" "<png path>" (Windows) — and tell the user a QR window just opened that they can scan with their phone. If the open command fails or the session is headless/remote, skip the QR entirely and present only the clickable URL — never leave the user hunting through collapsed tool output.

Channel-specific handoffs

If channel is slack, email, or telegram: deliver the handoff from Connect shell stdout, then Await until the CLI poll finishes.

Read Connect shell stdout (via Await, not log files) and act based on the chosen channel:

• slack — the connect run defaulted to the secure path, so first Await the secure setup link line and copy its value:

  NOVU_CONNECT_SLACK_SETUP_URL=<url>
  

  This is the moment the user must provide the token, so now present the token-delivery choice inline — call AskQuestion / AskUserQuestion with two options and recommend secure:

  • secure — Secure setup page (recommended) — paste the token on the page the CLI printed; it never enters chat.
  • in_chat — Paste token in chat (less secure) — the token then lives in chat history.

  If they pick secure (or skip the choice): paste that exact <url> into chat as a clickable link. Then tell them to:

  1. Open https://api.slack.com/apps and generate an App Configuration Token (access token starting with xoxe.xoxp-)
  2. Open the setup link and paste the token there — not in this chat

  The CLI polls until the token is saved (~5 min). Keep Awaiting the Connect shell — do not set a timer. When the token lands, stdout prints:

  NOVU_CONNECT_SLACK_CONFIG_TOKEN_SAVED=1
  

  Then Await the OAuth handoff line and copy its value:

  NOVU_CONNECT_SLACK_AUTHORIZE_URL=<url>
  

  Paste that exact <url> into chat, framing it as a fallback link — e.g. "If the Slack install page didn't open automatically, use this link to approve the install (within 5 minutes)." Await until the CLI poll finishes. Re-run on timeout (the Slack app is reused).

  If they pick in_chat: ask for the token in chat as free-text (not the picker), warn once that it will live in chat history, then kill the first Connect shell (the Step 3 process still polling the secure setup page) and re-run the Step 3 connect command once with --slack-config-token (set via an env var). That supersedes the secure setup page — the CLI skips the NOVU_CONNECT_SLACK_SETUP_URL handoff and goes straight to OAuth. Await the NOVU_CONNECT_SLACK_AUTHORIZE_URL=<url> line, paste that exact URL into chat as a fallback link — e.g. "If the Slack install page didn't open automatically, use this link to approve the install (within 5 minutes)."

• email — watch for these machine-readable lines (plain stdout, no ANSI):

  NOVU_CONNECT_INBOUND_ADDRESS=<address>
  NOVU_CONNECT_MAILTO=<mailto-url>
  NOVU_CONNECT_SEND_FROM_EMAIL=<email>   # only when present
  

  Give the user:

  1. The mailto link (NOVU_CONNECT_MAILTO=…) — one click opens a pre-filled draft in their mail client; this is the primary handoff.
  2. The inbound address as a copy-paste fallback.
  3. If NOVU_CONNECT_SEND_FROM_EMAIL is present, tell them to send from that address so the agent can reply.

  Then wait for the CLI poll — the process completes once the email arrives; on timeout, re-run after they've sent it.

• telegram — the connect run defaulted to the secure path. First, watch for the BotFather hint and secure setup link:

  NOVU_CONNECT_TELEGRAM_BOTFATHER_URL=<url>              # only when present
  NOVU_CONNECT_TELEGRAM_SETUP_URL=<url>
  NOVU_CONNECT_TELEGRAM_SETUP_QR_PNG=<absolute png path>   # only when present
  

  Tell the user to create a bot with @BotFather (https://t.me/botfather, send /newbot). The bot token is needed next, so now present the token-delivery choice inline — call AskQuestion / AskUserQuestion with two options and recommend secure:

  • secure — Secure setup page (recommended) — paste the token on the page/QR the CLI printed; it never enters chat.
  • in_chat — Paste token in chat (less secure) — the token then lives in chat history.

  If they pick secure (or skip the choice): paste the literal NOVU_CONNECT_TELEGRAM_SETUP_URL value into chat as a clickable link and tell them to paste the BotFather confirmation message on that page — not in this chat. When NOVU_CONNECT_TELEGRAM_SETUP_QR_PNG is present, also show the QR following Showing the QR code (host-aware) — never via a bare file read. The CLI polls until the bot token is saved (~5 min).

  If they pick in_chat: ask for the token in chat as free-text (not the picker), warn once that it will live in chat history, then kill the first Connect shell (the Step 3 process still polling the secure setup page) and re-run the Step 3 connect command once with --telegram-bot-token (set via an env var). That supersedes the secure setup page — the CLI skips the NOVU_CONNECT_TELEGRAM_SETUP_URL/QR handoff and goes straight to the deep-link step below.

  Then watch for the deep-link handoff:

  NOVU_CONNECT_TELEGRAM_DEEPLINK_URL=<url>
  NOVU_CONNECT_TELEGRAM_BOT_USERNAME=<name>
  NOVU_CONNECT_TELEGRAM_DEEPLINK_QR_PNG=<absolute png path>   # only when present
  

  When NOVU_CONNECT_TELEGRAM_DEEPLINK_QR_PNG is present, show the QR following Showing the QR code (host-aware). Ask them to open the bot and tap Start on @<botUsername>. Await until the CLI poll finishes. Re-run on timeout with the same command.

• whatsapp / teams (authenticated) — CLI prints a dashboard agent URL; paste it and tell the user to finish channel setup there.

• skip — nothing to hand off; the agent is created without a channel.

(Keyless + whatsapp/teams never reach this step — redirected in Step 1.)

Step 5 — Report the result

Goal: relay what the CLI printed, give a short recap of what onboarding set up, and point the user at the channel and the next step (claim link for keyless, dashboard for authenticated).

On success the CLI exits 0 and prints:

✓ Your agent is live.
  Agent: <name> (<identifier>)
  → Check <Channel> — your agent just messaged you.
  Dashboard: <dashboard url>            # authenticated only
  Claim your agent: <claim url>         # keyless only

Open the final report with the CLI's literal success line — copy the ✓ Your agent is live. line verbatim rather than paraphrasing it (e.g. "set up", "connected", "ready"); on failure, lead with the CLI's error instead. After leading with the CLI's result, give a 1–2 sentence recap of what onboarding set up — consistent with the conclusion-first operating principle. Before the channel/next-step pointer, briefly explain what the connect run built so the result isn't a black box. Keep it to one or two sentences, in plain language, e.g.:

"Here's what Novu built from your description: a hosted AI agent — its system prompt, the right tools and skills, MCP servers for the services you named, and a connection to <channel> so it can message your users."

Adapt the recap to what actually happened (drop the MCP clause when no integrations were named, name the channel that was connected, or say the agent was created without a channel for skip).

Then tell the user how to proceed.

Authenticated: after the recap, tell the user their agent is live in their Development environment — they can message it on the connected channel or open the dashboard URL to refine it (tweak its description and prompt, change tools, skills, and MCP connections, manage channels, and watch its activity).

Keyless: after the recap, surface the CLI's Claim your agent: link (not the dashboard agent URL). Explain the demo limit (~5 free replies) and that signing up via the claim link moves the agent, its channel, and the conversation into their own account — after that they can manage and refine it from the dashboard.

On failure, surface the error and matching fix:

Command flag reference

Run novu@latest connect --help for the full contract. Keep help text in sync when changing connect flags.

Limitations to keep in mind

• One run = one new agent + one channel. Re-running creates another agent.
• Channel support is uneven headlessly: slack and telegram need two user actions after auth; email one; whatsapp/teams need dashboard OAuth and finish in the dashboard.
• Prefer secure setup pages for Slack/Telegram tokens.
• Keyless data is temporary until claimed via the in-channel sign-up link.
• Keyless is the default for this flow — always pass --keyless unless a dashboard signal applies (then omit it for dashboard OAuth).

Definition of done

Keyless + WhatsApp / MS Teams: done when you've delivered the dashboard sign-in URL — no agent generated.

You are done when:

1. The user picked a channel and confirmed the agent description.
2. Keyless bootstrap succeeded (default, with --keyless), or dashboard OAuth completed (when omitting --keyless).
3. You delivered channel handoffs (or noted skip / whatsapp-teams dashboard URL).
4. Connect shell printed ✓ Your agent is live. (exit 0); CLI poll validated handoffs where applicable.
5. You reported agent identifier + next step (claim link for keyless, dashboard URL for authenticated), gave a brief recap of what onboarding set up, and explained how the user can keep going.