For AI agents: a Markdown version of this page is at https://docs.snowplow.io/docs/signals/quickstart.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt, and the index for this section is at https://docs.snowplow.io/docs/signals/llms.txt.
Signals quickstart with your coding agent
Add Signals to your web app with one command. The command sets up your project and your coding agent, and the agent then adds the tracking, the Signals configuration, and the code that uses it.
You'll need Node.js 18 or later, and a coding agent such as Claude Code, Cursor, or Codex. If you don't have a web app, the agent can create one.
Sign up
Create an account on the Signals free tier. It comes with a pipeline and Signals enabled, and needs no credit card.
Already on Snowplow CDI? Check that Signals is enabled.
Run the setup command
Run this in your project's root directory:
npx @snowplow/snowplow-cli signals setup
The command does the following:
- Opens a browser window for you to log in to Console
- Asks which Signals environment to use, if you have more than one
- Creates an API key with Signals permissions only and writes it to
.env - Installs the Snowplow plugin, with the Snowplow MCP server and skills, in Claude Code, Cursor, or Codex
- Offers to start your agent with a prompt that sets up Signals, or prints the prompt for you to paste
Keep .env out of version control. The command stops if it's already committed. For all options, see the command reference.
The agent asks what you want Signals to do. Describe the outcome, for example "show a different banner to visitors who've viewed pricing twice this session". It proposes a plan and waits for your approval, then asks again before it publishes anything. The first time it uses a Snowplow tool, a browser window opens for you to log in to Console.
Set up without the CLI
To set up by hand, install the plugin:
npx plugins add snowplow/skills
Get the four connection credentials and add them to .env as SNOWPLOW_SIGNALS_API_URL, SNOWPLOW_SIGNALS_ORG_ID, SNOWPLOW_SIGNALS_API_KEY_ID, and SNOWPLOW_SIGNALS_API_KEY. Then start your agent and send:
Use the signals-setup skill to set up Snowplow Signals in this project.
Check that it works
The agent finishes by showing live values and listing what it changed. To check for yourself, open the Signals section in Console to see the published configuration, or use the Snowplow Inspector to see attribute values as you use your app.
To check the credentials in .env, run:
npx @snowplow/snowplow-cli signals status
Troubleshooting
- If the browser login doesn't open, run
/mcpin Claude Code, select the Snowplow server, and choose Authenticate. For other clients, see authentication. - If
signals statusreports a problem, run the setup command again. It keeps credentials that work and replaces a rejected key. - If the setup command can't ask which Signals environment to use, for example when an agent runs it, pass
--pipelinewith the pipeline's name or ID. - If the attribute values are empty, generate a few more events in your app. Signals only calculates from events received after publishing. If they're still empty, check your browser's network tab for tracking requests to the Collector endpoint.
- If an ad blocker stops the tracking requests, turn it off for local testing. In production, serve the Collector from your own domain, or proxy the requests through your backend. See cookies and ad blockers.
Next steps
These pages explain what the agent built and other ways to work with Signals:
- Read How Signals works to understand the configuration the agent created
- Follow the conversational Signals tutorial for a longer walkthrough
- Prefer working in Console? Try the Console quickstart tutorial