Setup YAML reference

Prepare a file for the terminal setup command.

What this file does

The version 1 setup file describes one person. It uses YAML, a plain text format made of names and values. The top-level fields are version, consent, and person; all three are required.

Use freemyid setup --from FILE --check to validate the file and show the plan without saving. To import it, run freemyid setup --from FILE in a terminal, review the plan and permission text, then confirm. --yes confirms without a prompt. Without confirmation in a terminal, nothing is saved.

The full version 1 schema is the source of truth. Unknown fields are rejected.

freemyid setup --from setup.yaml --check
freemyid setup --from setup.yaml

Person and permission fields

Field	What it means
`version`	Use the number `1`.
`consent`	Required: set `agreed: true` and include `signed_name`. `basis` may be `self`, `guardian_of_minor`, or `authorized_agent`. An authorization file can be named with `authorization_file`.
`person.name`	Required: `first` and `last`. `middle` and `suffix` may be included.
`person.addresses`	Required: one to four addresses. Each needs `city` and a two-letter `state`. `street` and `zip` are optional; mark the current address with `current: true`.
`person` (optional fields)	`label`, `nicknames`, `previous_names`, `birth_year`, `age`, `phones`, `emails`, and `relatives` are optional. Use `age` if the birth year is unknown.
`permissions`	Optional choices: `allow_id_upload`, `allow_account_creation`, and `allow_phone_disclosure`. Each defaults to `false`.
`email_mode`	Choose `approve_each` or `auto`. The default is `approve_each`.
`schedule`	Optional: `weekly_recheck`, `weekday` (0 Monday through 6 Sunday), `hour` (0–23), and `install_job`. Defaults are weekly recheck on Sunday at 10, without installing a job.

Optional mailbox fields

A mailbox is optional. If you include one, provider and address are required. Providers are gmail, yahoo, icloud, proton_bridge, or other.

Passwords never belong in this file. Use password_env for the name of an environment variable, or password_file for a file path. Other optional fields include username, imap_host, imap_port, imap_ssl, imap_starttls, smtp_host, smtp_port, smtp_starttls, and tls_cert_sha256 for an approved Proton Mail Bridge certificate fingerprint.

Full fake example

This example uses made-up details. Replace them with the details you want to use, keep the file private, and do not put a mailbox password in it.

# Fake example only. Keep your real file private.
version: 1
consent:
  agreed: true
  signed_name: Jane Q Testperson
  basis: self
person:
  label: Jane
  name:
    first: Jane
    middle: Q
    last: Testperson
  addresses:
    - city: Springfield
      state: IL
      zip: "62704"
      current: true
  nicknames: [Janie]
  previous_names: [Jane Q Example]
  birth_year: 1980
  age: null
  phones: ["217-555-0142"]
  emails: [[email protected]]
  relatives: [John Testperson]
permissions:
  allow_id_upload: false
  allow_account_creation: false
  allow_phone_disclosure: false
mailbox:
  provider: gmail
  address: [email protected]
  password_env: FREEMYID_MAILBOX_PASSWORD
email_mode: approve_each
schedule:
  weekly_recheck: true
  weekday: 6
  hour: 10
  install_job: false

See the setup --from instructions for the confirmation and validation behavior.