chemenu/docs/reference/commands/configuration.md

Configuration

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

Contents

• config set
• config migrate

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

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

tools/wikitool config set tasks.stalled_waiting_days 14
tools/wikitool config set caldav.app_password --ref caldav_app_password
tools/wikitool config set caldav.username --ref op://Chemenu/caldav/username

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

config migrate

Move the settings out of the per-feature files of earlier versions into the tiered settings.

Synopsis

• wikitool config migrate

Options

  -h, --help  Show this message and exit.

Examples

tools/wikitool config migrate

Behaviour

• Moves the four per-feature settings files of earlier versions - telemetry, remotes, upload and the task tracker, each named in the migration document - into the sections telemetry, remotes, upload, and tasks, superproductivity and caldav: each value into the file its field's tier names, a secret's value into the secrets file with only a reference in wikitool.json.
• Every setting keeps its effective value, defaults included: the old content is read with the same checks the new sections use, and a field the old file did not set is not written.
• Run once per checkout, since the old files and .wikitool-local.json belong to one checkout. .wikitool-tools.json stays as it is.
• Prints each key and the file it went to, plus anything the old file held that was not read before and is not carried over - never a value.
• A second run, or a run with no old file, prints that there is nothing to move and changes no file.
• A key the target files already hold with a different value stops the move before anything is written: decide which one stands, remove the other, run again.

Properties

• Changes files: yes
• Idempotent: yes
• Atomic: Everything is computed and checked in memory first; the secrets file, wikitool.json and .wikitool-local.json are each replaced in one rename, read back and checked, and only then are the old files removed. Any failure before that puts every target back to the bytes it had and leaves the old files as they were
• Counts toward the session call budget: yes
• Can reach the network: no

Exit codes

• 0 - success
• 1 - An old file does not pass the check the new section applies, a target key holds a different value, or the files would not pass their check afterwards

See also

• wikitool doctor - reports every leftover old file as a FAIL
• docs/reference/configuration.md - the sections the files became
• instructions/migrations/10.0.0-settings-tiers.md - the migration this command belongs to