ApexDocsOpen Apex
Developer

Push and GitOps with `.drip.config.ts`

Use apex push to sync local experiment definitions to Apex with slug-based idempotent upserts.

apex push syncs local experiment definitions from a config file to the Apex API. It is idempotent by slug: the CLI sends each experiment to the slug upsert endpoint and reports whether the API created or updated it.

Config discovery

By default, the CLI looks in the current working directory for:

text
.drip.config.ts
.drip.config.js
drip.config.ts
drip.config.js

You can also pass a config path:

bash
apex push --config ./experiments/.drip.config.ts

TypeScript configs are bundled through esbuild before import. JavaScript configs are imported directly.

Supported exports

The config can export one experiment, an array of experiments, or an object with an experiments array.

ts
export default {
  experiments: [
    {
      slug: "homepage-hero-trust-copy",
      name: "Homepage hero trust copy",
      description: "Tests clearer proof copy in the homepage hero.",
      trafficAllocation: 0.25,
      storeUrl: "https://example-store.test/",
      targeting: {
        url: {
          type: "contains",
          value: "/"
        }
      },
      variations: [
        {
          slug: "control",
          name: "Control",
          weight: 0.5,
          isControl: true,
          mutations: []
        },
        {
          slug: "proof-copy",
          name: "Proof copy",
          weight: 0.5,
          mutations: [
            {
              selector: "[data-hero-subtitle]",
              action: "text",
              value: "Trusted by thousands of returning customers."
            }
          ],
          css: "[data-hero-subtitle] { letter-spacing: 0; }",
          js: "console.info('Apex variant loaded');",
          resetJs: "console.info('Apex variant reset');",
          antiFlickerSelectors: ["[data-hero-subtitle]"]
        }
      ],
      goals: [
        { id: "00000000-0000-4000-8000-000000000010" }
      ]
    }
  ]
};

Experiment fields

FieldRequiredAPI field sent by CLI
slugYesUpsert key in the URL.
nameYesname
descriptionNodescription
trafficAllocationNotraffic_allocation, defaulting to 1 when omitted.
storeUrl or store_urlNostore_url
targetingNotargeting
variationsYesMapped to variation payloads.
goalsNogoal_ids from each goal object's id.

Variation fields map both camelCase and snake_case names where the CLI supports them: isControl or is_control, css or custom_css, js or custom_js, resetJs or reset_js, and antiFlickerSelectors or anti_flicker_selectors.

Dry run

bash
apex push --dry-run
apex push --config ./experiments/.drip.config.ts --dry-run --json

Dry run loads and validates the config shape, checks that every experiment has a unique slug, and prints what would be pushed without calling the API.

Push

bash
apex push --json

The result includes counts for created, updated, and failed experiments plus a per-slug result array. If any experiment fails, the command exits non-zero and includes the partial result details.

Pairing with SDK definitions

Use .drip.config.ts as the local GitOps source for experiment definitions that pair with SDK-side defineExperiment or similar code-owned definitions. Keep slugs stable, keep API keys out of config, and use placeholders in examples rather than real shop IDs or client domains.