# `jadpo flags`

Change and remove flags.

Each flag's state is kept in the database `flags: { store: }` names (area 16). `jadpo flags` lists each flag with everyone's value, how many users are named, its shares, when it last changed, and whether it is ready to remove: every caller has had one value for seven days. `set` changes one part: with no option, everyone's value; --users gives named users the value; --percent gives it to that share of users, 0 removing the shares; --split gives each value its share. A `Bool` flag's value is true when an option is given without one. `reset` gives everyone the default again, or with --users stops naming those users. Each change is logged with the operator's name and database role. `remove` rewrites the source as if the flag had always held --keep's value, and checks the result. The database is the one --url names, or the one its connection's setting gives, or the one a running jadpo dev started.

Also: `jadpo flag`.

```text
jadpo flags [action] [flag] [value]
```

## Arguments

- `action` (optional): What to do: list, set, reset or remove
- `flag` (optional): The flag's name, as `flags.jadpo` declares it
- `value` (optional): The value `set` gives: true or false, or a variant's name

## Flags

- `--url <url>`: The database the flags' state is in
- `--users <ids>`: Users, by `id`, separated by commas
- `--percent <n>`: The share of users given it, 0 to 100
- `--split <shares>`: Each value's share of users: old=50,new=50
- `--keep <value>`: The value `remove` keeps wherever it is read

## On every command

- `--json`: Print data for tools instead of text
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo flags --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"flags"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# See every flag and who gets which value
jadpo flags
# Turn a flag on for 10% of users
jadpo flags set beta_banner --percent 10
# Compare two variants, half the users each
jadpo flags set banner_style --split old=50,new=50
# Remove a flag every user has had on for a week
jadpo flags remove beta_banner --keep true
```

## Errors

- [`cli.flags_arguments`](../errors/cli.flags_arguments.md): A `jadpo flags` command names an action it doesn't have, a flag the project doesn't declare, or a value, user or share the flag can't take
- [`flags.unavailable`](../errors/flags.unavailable.md): The flags' state couldn't be read or changed in their database, because it can't be reached, has no table for them yet, or changed while the command ran
- [`toolchain.artifact_write_failed`](../errors/toolchain.artifact_write_failed.md): A file Jadpo writes for you, such as a record, couldn't be written, usually because it or its folder is read-only
- [`toolchain.project_not_found`](../errors/toolchain.project_not_found.md): You ran a command that works on a project in a folder with no `app.jadpo`, in it or in any folder above it