CLIBeta

Run it with npx @klor/cli@beta, or add it as a dev dependency with npm install --save-dev @klor/cli@beta if a script or CI job uses it, and the command is klor. Spell out the package with npx: an unrelated package on npm is called klor. It reads the key from KLOR_API_KEY, or from --key.

export KLOR_API_KEY=klor_pub_…
npx @klor/cli@beta whoami
# Public key for the production environment, serving #42.

Which key a command needs depends on what it does:

klor types writes a declaration file listing your project's flags and their types. With it in your project, keys autocomplete, a misspelled key fails the build, and a fallback of the wrong type is refused. Without it, nothing changes: every key is a string, as it always was.

npx @klor/cli@beta types
# Wrote 12 flags to src/klor-flags.d.ts.

const checkout = useFlag('checkout_v2', false)   // boolean
const limit = useFlag('max_items', 25)            // number

useFlag('chekout_v2', false)
// Argument of type '"chekout_v2"' is not assignable to parameter of type …

The file goes in src/ if you have one and at the project root otherwise; --out puts it anywhere your tsconfig.json includes. Commit it, and run the command again after adding a flag. It needs @klor/react 0.4 or later. To stop using typed keys, delete the file.

JSON flags take their type from the fallback you pass, because only your app knows the shape it expects. The same types apply to useFlagDetail and to getFlag on the server.

A helper that wraps useFlag with a plain string key stops compiling once keys are typed, because any string is no longer a valid key. Type it the way the SDK does and it works with or without the file, and passes the checks through to its callers:

import { useFlag } from '@klor/react'
import type { FlagFallback, FlagKey, FlagResult } from '@klor/react'

// The fallback's type first, so useAppFlag<Theme>(...) works as useFlag<Theme>(...) does.
export function useAppFlag<T extends FlagFallback<K>, K extends FlagKey = FlagKey>(
  key: K,
  fallback: T,
): FlagResult<K, T> {
  return useFlag(key, fallback)
}

A public key cannot see flags marked sensitive, so a file written with one leaves them out, and an app typed from it cannot compile a read of a sensitive flag. That is the right answer for a client, where such a read only ever returns its fallback; generate with a secret or management key for server code.

To keep the file current in CI, check it rather than rewrite it, with the same kind of key the file was written with. Formatting is ignored, so Prettier, Biome, and Windows line endings do not make it fail; only added, removed, renamed, or retyped flags do.

npx @klor/cli@beta types --check
# src/klor-flags.d.ts is out of date. Run `klor types` to update it.   (exit 1)

A management key is scoped to one environment, so a pipeline holds one per environment it publishes to. Every command names the project and environment it is about to touch.

# Fail a build that left edits unpublished
npx @klor/cli@beta diff --exit-code

# Publish, with a note for the history
npx @klor/cli@beta publish --yes -m "Release 4.2"

# Serve an earlier snapshot again
npx @klor/cli@beta snapshots
npx @klor/cli@beta rollback 41 --yes

publish and rollback show what they will do and ask first. Outside a terminal they refuse unless you pass --yes, so a script never publishes on a guess. publish does nothing when there is nothing to publish.

klor pull downloads the published snapshot, so a build can ship with real values for a first launch with no network. Pass it as initialSnapshot; the SDK replaces it with a fresher one as soon as it can.

npx @klor/cli@beta pull -o src/klor.snapshot.json

import type { Snapshot } from '@klor/react'
import snapshot from './klor.snapshot.json'

const klor = createKlorClient({
  apiKey: 'klor_pub_…',
  // A JSON import widens literal fields, so TypeScript needs telling.
  initialSnapshot: snapshot as Snapshot,
})