From an empty repository to a published config

No sign-up yetThere is no console to sign up for yet. Early users get a project and keys from us: write to us.

1. Build the tools

   The CLI is one file that runs on Node 24. The web SDK installs from a tarball you pack once and keep with your release artifacts.

   Terminal

   # From a checkout of the UserCurrent repository
   pnpm install --frozen-lockfile
   
   # Build the CLI; it writes packages/cli/dist/uc
   pnpm --filter @usercurrent/cli build
   
   # Pack the web SDK; it prints the path of the .tgz
   pnpm --filter @usercurrent/sdk-web package:artifact

2. Give your agent the skills

   Nine skills cover setup, the tracking plan, personalization, the catalog, experiments, insights, audits and in-app messages. They are plain Agent Skills, so any coding agent that reads skills follows the same files.

   Terminal

   # Copy the skills into your app's repository, where your agent reads them
   mkdir -p .claude/skills
   cp -R /path/to/UserCurrent/packages/agent-skills/skills/* .claude/skills/
   
   # Then, in your agent:
   # > Set up UserCurrent for this app. Use the usercurrent-setup skill.

3. Write the config

   uc init writes a starter usercurrent.config.ts. The setup skill fills it in from your code, or you declare events yourself and let validate and scan check them.

   Terminal

   uc init        # writes usercurrent.config.ts
   uc validate    # checks the config and compiles it
   uc scan        # compares tracking calls with the plan

4. Add the web SDK or the Astro integration

   Collection stays off until you call setConsent. The endpoint and the public ingest key are under Settings, Install in your project. The Astro integration is for a site on Workers or Node, and it is source-only TypeScript in the repository for now.

   browser

   // npm install /absolute/path/to/usercurrent-sdk-web-0.2.0.tgz
   import { init } from '@usercurrent/sdk-web';
   
   const uc = init({ endpoint: 'https://events.example.com', key: 'pk_live_...' });
   
   // Call from your consent UI, with the choices the visitor made
   function onConsentChoice(analytics: boolean, personalization: boolean) {
     uc.setConsent({ analytics, personalization });
     uc.track('setup_complete');
   }

   astro.config.mjs and a page

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import usercurrent from '@usercurrent/astro';
   
   export default defineConfig({
     integrations: [
       usercurrent({
         client: './src/lib/usercurrent.ts',
         slots: { home_hero: { fallback: { headline: 'Welcome' } } },
       }),
     ],
   });
   
   // src/pages/index.astro: the variant is in the first HTML
   ---
   import { usercurrentOf } from '@usercurrent/astro/runtime';
   const hero = await usercurrentOf(Astro).slot('home_hero');
   ---
   <Hero {...hero.props} />

5. Publish to dev

   The console address, the project and a personal or agent key come from your console. Publishing is a dry run until you pass --apply, and an agent key cannot publish to Production. Then open Live events and confirm your first event arrived.

   Terminal

   export USERCURRENT_URL=https://console.example.com
   export USERCURRENT_PROJECT=YOUR_PROJECT_ID
   export USERCURRENT_TOKEN=...        # a personal or agent key from the console
   
   uc diff                                  # what differs from the project
   uc publish --environment dev             # a dry run
   uc publish --environment dev --apply     # save the drafts and publish them