splitchAlpha

Quickstart

Zero to a resolving Flag.

Install the CLI, create and verify a Flag in dev, connect the SDK, then turn the Flag on in prod.

Building with a coding agent?

Install the splitch skill in your repository. Codex, Claude Code, and OpenCode can follow these steps with the CLI and read its JSON output.

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

Sign in in your browser when your agent connects. In Claude Code, run /mcp if it does not prompt. There is no key to copy.

  1. Step 1 / 13

    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 / 13

    Choose or create an Organization

    List the Organizations you can access. If the list is empty, create one. Use the Organization's returned id as --org in the next step.

    splitch orgs list --json
# If the list is empty:
splitch orgs create --name "My Org" --json

  3. Step 3 / 13

    Create an App

    Replace <orgId> with your Organization's id. Creating an App also creates dev and prod Environments. Save the id of the entry with key dev in the returned environments array. You will need that canonical env_ ID to Promote to prod.

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

  4. Step 4 / 13

    Select the dev Environment

    Select the App and Environment to use for the following commands. This selection does not change your permissions.

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

  5. Step 5 / 13

    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 / 13

    Create a Flag

    Define the Flag once for the App, then configure it for each Environment. The CLI defaults the lifecycle class to release, the owner to you, and expiry to 90 days. A new Flag starts disabled and serves the Default Variant until you enable it and set a Percentage Rollout.

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

  7. Step 7 / 13

    Enable and roll out

    Enable the Flag and set its Percentage Rollout to 100% so every Targeting Key in this Environment gets the non-default Variant. See /docs/flags for Flag Configuration fields.

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

  8. Step 8 / 13

    Verify

    Verify the Flag for a Targeting Key without recording an Exposure. If the response has reason "DISABLED", enable the Flag before continuing. After enabling it, expect reason "SPLIT" and value true. This confirms that your credentials and Flag Configuration work in the selected Environment.

    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 / 13

    Install the SDK

    Install the JavaScript SDK in your app.

    npm install @splitch/sdk

  10. Step 10 / 13

    Wire the SDK

    Replace pk_... with the dev keyMaterial from client-key get, then run this example in a JavaScript module. It evaluates the Flag for test-user-1 and logs the result. Check for reason "ERROR" and use errorCode to handle a failed evaluation. SDK evaluations record Exposures only while an Experiment Run is live. This plain Flag has no Experiment Run, so it records no Exposure.

    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: "test-user-1",
});
if (d.reason === "ERROR") throw new Error(d.errorCode);
console.log(d.value, d.variantName, d.reason);

  11. Step 11 / 13

    Promote to prod

    Promote the enabled state and Percentage Rollout from dev to prod. Replace <devEnvironmentId> with the id of the dev entry in environments[] from App creation. --from-environment-id requires the canonical env_ ID, while --env accepts the key prod. New Apps use the confirm Policy for these prod changes. This command returns APPROVAL_REVIEW_REQUIRED with exit code 4 and a pending Approval Request. Prod stays unchanged until Confirmation.

    splitch flags promote new-checkout --env prod --from-environment-id <devEnvironmentId> --body-json '{"select":{"enabled":true,"rollout":true}}' --idempotency-key promote-1 --json

  12. Step 12 / 13

    Review and confirm the Promotion

    Inspect the Approval Request using details.approvalRequestId from the previous response. When you are ready to apply it, rerun the same Promotion command with the same idempotency key and add --confirm. Under the confirm Policy, this Confirmation lets you self-review and apply the pending Approval Request.

    splitch approval-requests get <approvalRequestId> --json
splitch flags promote new-checkout --env prod --from-environment-id <devEnvironmentId> --body-json '{"select":{"enabled":true,"rollout":true}}' --idempotency-key promote-1 --json --confirm

  13. Step 13 / 13

    Verify prod and connect your app

    Verify the Flag in prod, then fetch prod's Client Key. Replace the SDK example's clientKey with the returned keyMaterial to connect your production app. Each Environment has its own credential. Restrict the Client Key to your production origins before shipping it.

    splitch flags verify new-checkout --env prod --targeting-key test-user-1 --json
# {"value":true,"variantName":"on","reason":"SPLIT"}
splitch client-key get --env prod --json

When a step fails

If a command fails, read its error code and follow the recovery steps below. Agents can use the recommendedAction field in a 409 response to choose the next action.

You hitIt meansDo
APPROVAL_REVIEW_REQUIREDthe Environment Policy gates this changeinspect the Approval Request, then provide Confirmation if you intend to apply it
VARIANT_NOT_AVAILABLEthe Variant is not promoted to this Environmentpromote the Variant to this Environment, then retry
RUN_FROZENthe edit touches a running Experiment Runclone into a new draft Experiment Run
APP_MISMATCHwrong key for this App or Environmentfetch the credential for this Environment
401 / 403bad or revoked key, or origin not allowedcheck the key and its origin allow-list