Agora

Flags 1.x is a release candidate. npm's latest tag still installs 0.x, so install these docs' version from the rc tag:

npm i @adonis-agora/flags@rc
node ace configure @adonis-agora/flags

The same goes for every @adonis-agora/* package these docs install: add @rc, and where a page says node ace add, install with @rc first and then run node ace configure. On 0.x? Read the 0.x docs.

CLI

Every flags:* ace command — everything the console does, from the terminal.

Everything you can do in the console you can do with node ace. The commands run the console's own handlers, so the same validation, permissions, approvals and audit trail apply.

Conventions

  • --env=<name> picks the environment (default: the one this app evaluates).
  • --json prints JSON instead of a table, on every list and show.
  • Writes act as cli:<your OS user> in the audit; --as=<id> acts as someone else.
  • --note="…" is kept on the change request and in the audit.
  • In an environment with approvals, a write files a change request instead of applying: the command says so and prints its id.
  • Deleting, replacing a ruleset and forgetting a subject ask for confirmation. Pass --force to skip the question; without a terminal (CI, a pipe) --force is required.
  • JSON inputs (--definition, --segment, …) take inline JSON or @path/to/file.json.
  • A refused change prints one error line and exits with code 1.

Flags

CommandWhat it does
flags:listEvery flag: declared type and default, what it serves, owner
flags:flag:show <flag>Declaration, targeting, what it serves, pending requests, schedules, last changes
flags:set <flag> <value>Shortcut: on, off, kill, unkill, 25%, a variant name, or a value (flags:set max_uploads 25)
flags:flag:enable <flag> / flags:flag:disable <flag>The kill switch
flags:flag:rollout <flag> <percent>Serve on to a share of subjects (on/off flags)
flags:flag:variant <flag> <variant>Serve one variant to everyone
flags:flag:override <flag> <subject> <variant>Force a variant for one subject; --clear removes it
flags:flag:save <flag> --definition=<json>Save the whole definition (variants, rules, overrides, fallthrough, experiment)
flags:flag:create <flag> --declaration=<json>Create a flag without code ({ "type": "boolean", "default": false })
flags:flag:update <flag> --declaration=<json>Edit a console-created flag's description, owner, tags, expiry
flags:flag:drop-declaration <flag>Drop the console declaration of a flag the code now declares; the targeting stays
flags:flag:delete <flag> [--force]Remove a flag from the ruleset; the code default takes over
flags:flag:evaluate [flag] [--subject] [--context=<json>]What a subject would get. Records no exposure
flags:types [--out] [--no-strict]Generate TypeScript types for the flags created in the console
node ace flags:flag:rollout new_player 25 --note "ramp"
node ace flags:flag:override checkout qa-team one_page
node ace flags:flag:evaluate checkout --context='{"targetingKey":"u1","country":"BR"}'

Segments, layers, holdout, metrics

CommandWhat it does
flags:segments:listSegments and the flags whose rules use each one
flags:segments:save <key> --segment=<json>Create or replace a segment
flags:segments:delete <key> [--force]Delete a segment (refused while a rule uses it)
flags:layers:listLayers, their allocations, the global holdout and every experiment
flags:layers:save <key> --layer=<json>Create or replace a layer
flags:layers:delete <key> [--force]Delete a layer
flags:holdout:save --holdout=<json>Set the global holdout ({ "percent": 5 }); --clear [--force] removes it
flags:metrics:listMetrics from config/flags.ts and the console, and who uses them
flags:metrics:save <name> --metric=<json>Create or replace a console metric
flags:metrics:delete <name> [--force]Delete a console metric (refused while an experiment uses it)
node ace flags:segments:save staff --segment='{"conditions":[{"attribute":"email","op":"endsWith","values":["@acme.com"]}]}'
node ace flags:metrics:save purchases --metric='{"kind":"conversion","event":"purchase"}'

Experiments

CommandWhat it does
flags:experiments:listEvery experiment: running, exposures, SRM, verdicts of the last results
flags:experiments:show <experiment>The last computed results
flags:experiments:recompute <experiment>Compute the results now instead of at the worker's next tick

Approvals, schedules, audit

CommandWhat it does
flags:requests:list [--status] [--first]Change requests, newest first. --status is pending (default), approved, rejected, applied, cancelled or all
flags:requests:approve <id> [--note]Approve and apply. The requester cannot approve their own
flags:requests:reject <id> [--note]Reject
flags:requests:cancel <id>Withdraw your own request
flags:schedules:list [--flag] [--status] [--first]Scheduled changes, soonest first
flags:schedules:create <flag> --kind=<enable|disable|rollout> --at=<date> [--percent]Schedule one change
flags:schedules:create <flag> --steps=<json>A gradual rollout: [{ "at": "…", "percent": 10 }, …]
flags:schedules:cancel <id>Cancel a pending schedule
flags:audit:list [--entity] [--key] [--first] [--after]Who changed what, newest first. The last line prints the --after for the next page
node ace flags:requests:list --env=production
node ace flags:requests:approve 01JC… --env=production --note "checked with support"
node ace flags:audit:list --key=checkout --first=20

Environments

CommandWhat it does
flags:environments:listEnvironments, and which ones need approvals
flags:export [--out]The ruleset as JSON
flags:import <file> [--dry-run] [--force]Replace a ruleset (validated; approvals apply)
flags:promote <from> <to> [--dry-run] [--force]Copy one environment's ruleset over another

--dry-run validates the replacement against the target environment and changes nothing.

Hygiene and operations

CommandWhat it does
flags:stale [--unused-days] [--static-days]Flags that are probably safe to remove
flags:refs [--flag]Where each flag is used in the code
flags:ops:statusRuleset source, buffer, transport, sinks and tenants
flags:work [--once] [--sink]Run the background work: relay, schedules, results, maintenance
flags:replay <sink>Deliver the retained event log to a sink again
flags:forget <subject> [--force]Delete everything stored about a subject

On a tenant app the commands refuse: run them on the control-plane.

Upgrading from 0.6

Two commands are renamed, without an alias:

Before (0.6)Now
flags:requests listflags:requests:list
flags:requests approve <id>flags:requests:approve <id>
flags:requests reject <id>flags:requests:reject <id>
flags:requests cancel <id>flags:requests:cancel <id>
flags:results <experiment>flags:experiments:show <experiment>
flags:results <experiment> --freshflags:experiments:recompute <experiment>

Scripts and CI jobs also need these changes:

  • flags:import, flags:promote and flags:forget ask for confirmation. Without a terminal they refuse, so pass --force.
  • flags:stale refuses an --unused-days or --static-days below 1.

On this page

Partner

Your product as the official integration for Flags, right here.

Become a partner →