/rudder-setup

name: rudder-setup
description: Takes an app from no analytics to one real event delivered to a destination the user picks, with the pipeline as rudder-cli specs in git. Use when the user says "set up RudderStack", "onboard" or "send my first event", or when the RudderStack Get started card or plugin sent them here.
allowed-tools: Bash(rudder-cli *), Bash(git *), Bash(npm *), Bash(npx *), Bash(curl *), Bash(jq *), Bash(test *), Bash(ls *), Bash(grep *), Bash(wc *), Bash(date *), Bash(mkdir *), Read, Write, Edit, Grep, Glob

Set up RudderStack in this project

Done means one real event reached the destination the user chose. The app sends it, or curl does when there is no app here. The destination's delivery count proves it, and so does the payload at the destination when the user can read it there. The pipeline exists as specs in `rudder/` and every change is committed, so `git revert` followed by `rudder-cli apply` undoes it. The user makes three decisions: the plan (what to learn and which events), where events go, and whether to apply the specs.

When to use

• The user asks to set up RudderStack, add analytics, or send a first event, in a repository you can edit.
• The user pasted the prompt from RudderStack's Get started card, or ran the onboarding command of the RudderStack plugin.
• Best started in the app that will send events. Started in an empty folder, the home folder or a folder of several repositories, step 1 recommends starting again in the app, and can instead continue with a first event sent by curl.
• Not for a workspace that already has CLI-managed resources from another project. Step 2 stops in that case.

Before you start

• **rudder-cli**: check with `rudder-cli --version`. If missing, install with `d=$(mktemp -d) && curl -fsSL https://github.com/rudderlabs/rudder-iac/releases/latest/download/install.sh -o "$d/install.sh" && sh "$d/install.sh"`. The command downloads the installer into a new temporary folder, then runs that file; do not pipe it into a shell. It is the installer attached to the latest rudder-iac release. It installs that release's archive for this OS and CPU in `~/.local/bin`, after checking it against the release's checksums file. If a plain `rudder-cli` then runs another copy or none, follow the full-path rule under Rules that hold in every step. If the download of the installer prints `The requested URL returned error: 404`, a release came out in the last few minutes and its files are still uploading. Wait one minute and run the same command again, up to 10 times. Go by that message, not by curl's exit code, which is 22 or 56 for the same 404. If the last try also gets a 404, tell the user that a new rudder-cli release is being published and that they can try again in a few minutes, and stop. A line that starts with `rudder-cli install:` comes from the installer, which ran and failed; that is not the 404 above, even when a curl message comes before it, so do not retry. If curl cannot reach github.com, or the installer says it cannot write to `~/.local/bin`, the agent's sandbox is the likely cause. Ask the user to let the command run outside the sandbox or to run it in their own terminal, and never set `RUDDER_CLI_INSTALL_DIR` to a folder inside the project. For any other `rudder-cli install:` line, show it to the user and stop. This skill needs the first rudder-cli release that contains rudder-iac#989 (`docs destination`) and #990 (validate's `destination/secret-reference` warning). Step 1 checks for both features, not for a version, because a build from source reports 0.0.0 (fact cli-features). A rudder-cli that has them also has step 7's `sources listen`.
• **git**: check with `git --version`.
• **jq**: check with `jq --version`. Steps 3 and 7 run the jq programs shipped with this skill. If jq is missing, ask the user to install it, for example with `brew install jq` or `sudo apt-get install jq`.
• **the rudderstack MCP server**: check that the tools list_sources, get_source and get_destination_event_metrics are available to you. It is the HTTP server at https://mcp.rudderstack.com/mcp. It signs in with the user's RudderStack login in the browser (OAuth), not with the access token. If no plugin added it, the user adds it, see step 1. An MCP server added during a session loads only after a restart. A server at https://mcp.rudderstack.com/bearer-auth-mcp, the access-token route for sessions that cannot open a browser, works too. It has no sign-in and no `user_details`: it sends the token in `RUDDERSTACK_ACCESS_TOKEN` and reads the workspace from its `X-Workspace-ID` header.
• **RUDDERSTACK_ACCESS_TOKEN** (environment variable): A read-write access token for the workspace, exported in the shell the agent was started from, or saved with `rudder-cli auth login`. `rudder-cli workspace info --json` succeeds when rudder-cli has one. The user creates one on Get started or in Settings, Access tokens. It is for rudder-cli only; MCP signs in separately. Never ask the user to paste it into chat, and never echo it.

Rules that hold in every step

• Begin each step with one line, `Step N of 9 · <title>`, so the user can follow along.
• After you install rudder-cli, run `command -v rudder-cli`. If it prints nothing, or a path other than `$HOME/.local/bin/rudder-cli`, a plain `rudder-cli` does not run the copy you installed. Then, for the rest of the session, run `"$HOME/.local/bin/rudder-cli"` wherever this skill or its references say `rudder-cli` in a command, probes and recipes included. Do the same when step 1 settles on a copy that an earlier install left in `~/.local/bin`. Tell the user once that you run rudder-cli by its full path. When you ask the user to run a rudder-cli command, such as `rudder-cli auth login`, give it with the full path as well. Do not ask them to edit a shell profile or to restart you for this. Step 9's summary gives them the `export PATH` line, and so does your last message whenever you stop before step 9. `allowed