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.