Flags quickstart

A flag decides a value per request instead of at deploy time. This takes one from nothing to a value a specific audience reads: the segment that describes the audience, the flag, the rule that points at the segment, and the evaluation that proves it.

#1. Create the segment

A ConfigSegment is an audience of one environment: subjects named by id, and conditions over the evaluation context. Its id is what a rule's IN_SEGMENT names, so it is a name worth choosing deliberately.

sylphx config config-segments create --parent orgs/acme/projects/shop/envs/production

The spec is the audience. included lists the ids always in the segment, excluded the ids never in it whatever else holds, and conditions the comparisons everyone else must pass. A segment with neither conditions nor exclusions is exactly the ids you list.

#2. Create the flag

sylphx config config-flags create --parent orgs/acme/projects/shop/envs/production --spec.value-type bool

The flag is one typed value: value_type fixes the type every value it serves has, and default_value is the value an evaluation gets when no rule matches, or when the flag is turned off. The same call over HTTP, with the default written out:

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/config_flags" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"default_value":{},"value_type":"bool"}}'

#3. Point it at the audience

Targeting lives in spec.rules, which the CLI writes with --spec.rules. Each rule carries the value to serve and the conditions that must all hold; a condition whose operator is in_segment names a segment's id — the segment of this walkthrough is config-segment — which is why the id was worth choosing. The rules are part of the spec, so update writes them:

sylphx config config-flags update orgs/acme/projects/shop/envs/production/config_flags/config-flag

Rules are read in order and the first match wins, so a rule with no conditions at the top would shadow every rule below it. Under the rule's value, a percentage below 100 serves that value to a share of the matching evaluations and lets the rest fall through to the next rule. Targeting rules covers the conditions and the rollout in full.

#4. Evaluate

sylphx config config-flags evaluate orgs/acme/projects/shop/envs/production

The call takes an evaluation context — user_id, anonymous_id, and any attributes the rules compare — and the ids of the flags to evaluate. An empty list evaluates every flag of the environment. Each flag answers with its value and the reason for it: targeting_match, split, default, disabled or not_found for an id the environment does not have.

#5. Read it back

sylphx config config-flags get orgs/acme/projects/shop/envs/production/config_flags/config-flag

status is the rollout's own view, not the spec you wrote. conditions holds Ready, Reconciling or Stalled — Reconciling while a change rolls out in waves, Stalled when a wave's health gate fails and the change halts — and wave, wave_count, updated_cell_count and cell_count say how far the change has reached.

sylphx config config-flags snapshot orgs/acme/projects/shop/envs/production

#Next