splitch

Quickstartsplitch://quickstart

Zero to a resolving Flag.

This page walks the CLI path, and every step ends on a verify round-trip. Building with an agent? Don’t paste this page into its context: connect it to mcp.splitch.dev and it discovers the tools, and this same sequence, in-band via splitch://quickstart.

authenticate → pick an Org → create an App (dev+prod Envs auto-provisioned)
            → select the dev Environment → get a Client Key → create a Flag
            → enable + rollout → VERIFY (reason SPLIT) → wire the SDK → first real Exposure

  1. Step 1 / 9

    Install and authenticate

    The CLI ships on npm and needs Node 20+. Log in with the device flow: it prints a verification URL and polls until approved.

    npm install --global @splitch/cli
splitch login

  2. Step 2 / 9

    Pick an Organization

    Discover the Organizations your token can reach, then pick one.

    splitch orgs list

  3. Step 3 / 9

    Create an App

    A dev and a prod Environment are auto-provisioned. You do not create Environments by hand for the common case.

    splitch apps create --org <orgId> --name "My App"

  4. Step 4 / 9

    Select the dev Environment

    Active context fills in IDs on every later call. It is convenience only and never widens authorization.

    splitch use --app my-app --env dev

  5. Step 5 / 9

    Get your credential

    The Client Key is public and safe to ship in a browser. The API Key is secret, surfaced once, for trusted servers. New Client Keys start open to all origins so they work immediately; lock them to your origins before production.

    splitch client-key get

  6. Step 6 / 9

    Create a Flag

    Flag definition is App-level; serving config is per-Environment. A fresh Flag starts disabled with rollout null — it only ever serves the Default Variant until you flip Configuration.

    splitch flags create --key new-checkout --variants on,off

  7. Step 7 / 9

    Enable and roll out

    Turn the Flag on and set the baseline rollout to 100% so every Targeting Key in this Environment gets the non-default Variant. Configuration fields are documented at /docs/flags.

    splitch flag-config update new-checkout --enabled true --rollout 100

  8. Step 8 / 9

    Verify

    Confirm the Flag resolves for a Targeting Key without firing an Exposure. reason "DISABLED" means the Flag is still inert (enabled false) — that is not a pass. After the enable step you should see reason "SPLIT" and value true. One green round-trip with SPLIT proves auth, Environment, credential, and Flag config all line up.

    splitch flags verify new-checkout --targeting-key test-user-1 --json
# before enable: {"value":false,"variantName":"off","reason":"DISABLED"}
# after enable:  {"value":true,"variantName":"on","reason":"SPLIT"}

  9. Step 9 / 9

    Wire the SDK

    evaluate() fires the first real Exposure and closes the loop. Fail-loud is one check: an error resolution names its code instead of hiding behind a default.

    import { createSplitchClient } from "@splitch/sdk";

// Paste keyMaterial from `splitch client-key get` (pk_…; not the ck_… keyId).
const splitch = createSplitchClient({ clientKey: "pk_..." });

const d = await splitch.evaluateDetails("new-checkout", { targetingKey: userId });
if (d.reason === "ERROR") renderFallback(d.errorCode);
else render(d.value);

When a step fails

splitch fails loud, then guides. Every operational 409 carries a machine-stable recommendedAction token. Branch on the token, not on prose.

You hitIt meansDo
APPROVAL_REVIEW_REQUIREDthe Environment Policy gates this changereview the durable request
VARIANT_NOT_AVAILABLEthe Variant is not promoted to this Environmentpromote the Variant to this Environment, then retry
RUN_FROZENthe edit touches a running Runclone into a new draft Run
APP_MISMATCHwrong key for this App or Environmentfetch the credential for this Env
401 / 403bad or revoked key, or origin not allowedcheck the key and its origin allow-list