CLI command
flags
Feature flags with declared rollouts, optionally rolled out by the arms of an adaptive experiment: each subject's decision is made once, recorded with its reason, and answered the same on every later read.
Invocation#
echo-cli flags list --product <id>
echo-cli flags set --product <id> --key <flag> --rollout <0-1> --always-on <subject,...|''> [--experiment <experiment-id> --on-arms <arm,...>] --by <name>
echo-cli flags read --product <id> --key <flag> --subject <user-or-anonymous-id>
echo-cli flags selections --product <id> --key <flag>Inputs and output#
list writes the product's flags: product_id, key, rollout, always_on, experiment_id (the adaptive experiment it follows, null for none), on_arms (the arms it is on in), set_by, set_at, selected (subjects decided) and on (of them, on). set writes the flag. read writes key, subject, on, reason (listed in always_on; drawn against rollout <r>; assigned arm <arm> of experiment <id>, drawn against rollout <r>; or assigned arm <arm> of experiment <id>, which the flag is off in), rollout and selected_at. selections writes the flag's recorded decisions, newest first.
State effect#
list, set and selections call Echo Web's authenticated /api/analytics/flags with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; read calls GET /api/public/flags, the endpoint products call for their users and visitors without signing in. The Feature flags section of the tracking screen and of Echo Desktop's GEO screen declares flags, including the experiment and arms a flag follows, and shows their selections, and echo-mcp lists flags (echo_list_flags). The first read for a subject decides the flag: on when the subject is in always_on; for a flag following an experiment, by the arm the experiment assigned the subject (stored in adaptive_assignments) — in an arm the flag names, on with the probability the rollout states (1 puts it on for all of them), in any other arm off; otherwise on with the probability the rollout states. The decision is stored with the rollout it was made under, and every later read answers it, so a subject never flips. A changed rollout, always_on list or arm list applies to subjects not decided yet.
Refusals#
- A wrong invocation is refused before anything is sent: "flags takes <every verb's usage, separated by semicolons>; got <word>", "flags <verb> does not take <flag>; it takes …", "<flag> needs a value", "flags <verb> needs <flag>" for each flag the verb needs, and "--rollout must be a number from 0 to 1; got <value>".
- Echo Web answers a bad request with "product_id is required: …", "key is required: …", "subject is required: the user or anonymous id the flag is read for", "rollout must be a number from 0 to 1: the share of subjects the flag is on for; got <value>", "always_on is required: the list of subject ids the flag is on for whatever the rollout, empty when there are none", "on_arms names arms of an experiment, so experiment_id is required beside it", "on_arms is required with experiment_id: the list of the experiment's variant keys the flag is on in, at least one", "experiment <id> has no arm <arm>; its arms are <arms>" or "set_by is required: an internal caller has no signed-in user, so it names who is acting", and not found with "no product has id <id>; echo-cli products lists the ones that exist", "no adaptive experiment <id> has variants; echo-cli experiments lists the experiments", "product <id> declares no flag <key>; echo-cli flags set declares it" or, for a flag following an experiment, "<subject> has no arm in experiment <id> yet, and flag <key> follows its arms; the product assigns the subject through /api/experiments/assign first" (nothing is recorded, so the decision waits for the arm). The command prints Echo Web's sentence and exits non-zero.