# Configuration

Writing the tiered settings in `wikitool.json` and `.wikitool-local.json`.

<!-- wikitool:reference-commands -->
## `config set`

Set one value of the tiered settings, in the file its tier names.

**Synopsis**

- `wikitool config set <section>.<field> <value>`
- `wikitool config set <section>.<field> --ref <name|op://vault/item/field>`

**Options**

```text
Arguments:
  key    <section>.<field>  [required]
  value  The plain value; a string as given, anything else as JSON.

Options:
  --ref <str>  A reference instead of a value: <name> or
               op://<vault>/<item>/<field>.
  -h, --help   Show this message and exit.
```

**Examples**

```bash
tools/wikitool config set tracker.stale_days 14
tools/wikitool config set tracker.token --ref tracker_token
tools/wikitool config set tracker.url --ref op://Chemenu/tracker/url
```

**Behaviour**

- Writes a plain value of a field of tier `instance` into `wikitool.json`, and one of tier `checkout` - a private field's included - into `.wikitool-local.json`.
- With `--ref`, writes a reference instead of a value into `wikitool.json`: `<name>` resolves through `WIKITOOL_SECRET_<NAME>`, then the secrets file in the user's configuration directory; `op://<vault>/<item>/<field>` resolves through the 1Password CLI. Only a secret or private field takes one.
- Removes the same key from the other file, so a value never has two places, and says so.
- Creates `wikitool.json` with a fresh `instance_id` the first time it writes anything; the secrets file is found by that id.
- Checks both files as they would stand after the write against every registered section, and writes nothing when that fails.
- Prints the key and the file it wrote, never the value. Resolves no reference.

**Properties**

- Changes files: yes
- Idempotent: yes
- Atomic: Each file is replaced in one rename; both are checked before either is written
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `0` - success
- `1` - The key names no registered section or field, or is not `<section>.<field>`
- `1` - A plain value given for a field of tier `secret`
- `1` - `--ref` given for a field that takes a plain value, or a malformed reference
- `1` - The value is not of the field's type, or the files would not pass their check afterwards
- `42` - The field names a program to run or affects a gate

**See also**

- `wikitool doctor` - whether both files pass and every reference resolves
- `docs/reference/configuration.md` - the files, the tiers and the references
- `docs/how-to/use-1password-for-settings.md` - setting 1Password up as the source
<!-- /wikitool:reference-commands -->