CLI.

The CLI is the same control plane the Control Panel drives, with one command per operation. Install it globally and authenticate once; the session is stored per machine.

npm install --global @splitch/cli
splitch login
splitch context --json

splitch context is the command to run first and after anything surprising: it reports the authenticated principal and the resolved App and Environment, and it fails loud rather than reporting an empty success.

Scope: App and Environment

Most commands operate on one App, and many on one Environment inside it. Both are resolved in the same order every time, first match wins:

• --app / --env on the command.
• SPLITCH_APP / SPLITCH_ENV in the environment.
• splitch.json in the current directory or an ancestor, written by splitch use.

splitch use --app checkout --env dev
splitch flags list --json

Project configuration

Place splitch.json in a project directory to select its App automatically. The file is optional. The CLI checks the current directory and then each parent directory, stopping at the nearest file. This lets commands run from any nested package or source directory without repeating --app.

{
  "version": 1,
  "app": "app_...",
  "environment": "env_..."
}

environment is optional when the repository should select only the App. The file contains no credentials and is safe to commit. splitch use --app <app> [--env <env>] validates the selectors, writes canonical IDs, and updates the nearest existing splitch.json. If no parent contains one, it creates the file in the current directory.

An unresolved selector is a refusal (CLI_SCOPE_UNRESOLVED, exit 3), never a silent pick of the only App you can see.

--json on every command

--json prints the response body as one line on stdout, with nothing else on that stream. Failures answer in the same shape, so a caller branches on a field instead of matching a sentence:

{"code":"APPROVAL_REVIEW_REQUIRED","message":"...","remediation":"...","docsUrl":"https://splitch.dev/docs/error/APPROVAL_REVIEW_REQUIRED","details":{"approvalRequestId":"apr_..."}}

• code is the stable identity. message says what happened, remediation says what to do next, and docsUrl resolves to the page for that code.
• details carries the fields you have to act on (approvalRequestId, frozenFields, policyContexts) and is null when the failure has none.
• The human sentence is written to stderr either way, so --json never costs you the readable error.

--confirm on Policy-gated changes

An Environment Policy can require confirmation or review before a change applies. A gated command refuses first and tells you which; it never applies half of a change. Re-run with --confirm when the Policy asks for confirmation:

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

When the Policy requires review instead, the refusal carries details.approvalRequestId and --confirm will not bypass it. The --confirm column below marks every command that parses the flag.

Secrets

splitch api-keys create returns the raw API Key under value, once. It is never readable again, so a run whose stdout is captured to a log has published the credential permanently. Pass --output-file to keep it off both streams:

splitch api-keys create --body-json '{"scopes":["data-plane:evaluate"]}' --output-file ./.splitch-api-key --json

The secret lands in one new 0600 file and the payload reports value: null with valueWrittenTo naming the path. The command refuses a path that already exists, before the Key is minted. A Client Key is public and needs none of this: read it any time with splitch client-key get.

Temporary Environments

A Temporary Environment is an expiring copy of another Environment in the same App, with its own Flag Configurations, Client Key, and API Keys. Use one per branch or pull request instead of editing a shared dev:

splitch envs create --key pr-123 --temporary --from dev --json
splitch envs sync --env pr-123 --from dev --json
splitch envs delete --env pr-123 --json

Creation returns the Client Key. The copy expires 7 days after creation unless --expires-at names an earlier day count such as 3d or an ISO 8601 instant, and expiry cannot be extended. Sync replaces every Flag Configuration with the source's, including rollout salts, and never copies a live Experiment Run. Its Policy allows every change and it cannot host Experiments. After expiry, its keys and every mutation except envs delete fail with ENVIRONMENT_EXPIRED until teardown removes it; deleting it starts teardown immediately.

An agent token created with --grant app:<app id>:owner:temporary_environments reads the whole App and writes only inside Temporary Environments. The same command against a permanent Environment or an App-level resource is refused with FORBIDDEN.

Query flags from the route schema

List and other routes that declare OpenAPI query parameters expose them as kebab-case flags derived from the schema (--cursor, --limit, --status, --run-id, and so on). Required query fields fail loud when omitted; invalid typed values fail with CLI_USAGE_INVALID. Hand-mapped flags such as --env, --by, --dry-run, and --from-environment-id keep working. If a query field's kebab name collides with a reserved global flag, the reserved flag wins and the query field is not re-derived under that name.

splitch approval-requests list --cursor page_2 --limit 25 --json

Exit codes

Command reference

Every command accepts --json and --help. splitch <resource> <action> --help prints the arguments, flags, and an example for that one command.