splitchAlpha

Quickstartsplitch://quickstart

Zero to a resolving Flag.

This page walks the CLI path, and every step ends on a verify round-trip.

Building with a coding agent?

Install the Splitch skill in the consumer repository. Codex, Claude Code, and OpenCode will use the CLI and its stable JSON output instead of operating the Control Panel in a browser.

npx skills add https://github.com/zaks-io/splitch/tree/main/skills/splitch

For an agent with native MCP support, you can also connect the remote server directly.

claude mcp add --transport http splitch https://mcp.splitch.dev

Your agent calls that endpoint and signs in on its first tool call, so there is no key to copy.

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. 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