Settings overview

Friday stores all of your preferences in ~/.friday/.user_preferences.yaml. The leading dot makes it a hidden file: ls ~/.friday won't show it without -a. The format is YAML.

You can edit settings two ways: from inside Friday with the /settings slash command, or by opening .user_preferences.yaml in your editor. Both write to the same file. For the full list of keys and defaults, see the Settings reference.

Two ways to edit

/settings (recommended)

Type /settings in Friday's prompt to open the settings menu. Pick a setting, choose a value, and Friday writes the change to the file for you. This is the safe path: every option is validated, defaults are filled in, and the file stays well-formed.

Most changes made through /settings take effect immediately for the thread you ran the command from. A few settings (notably Working Style) only refresh the thread you triggered them from; threads that were already running keep their prior values until they finish. The Working style page covers that nuance.

Editing .user_preferences.yaml directly

If you prefer to edit on disk, open ~/.friday/.user_preferences.yaml in any text editor. This is useful for bulk changes, copying a configuration between machines, or tweaking values that are easier to type than to click through. Two things to keep in mind:

  • The file must be valid YAML. Mismatched indentation or a stray colon will prevent Friday from starting.
  • Most settings are read on startup. Restart Friday after editing the file directly to be sure your change is picked up.

Layers: user-global vs. per-project

Settings come in two layers:

  • User-global. The top level of .user_preferences.yaml. These apply to every project unless overridden.
  • Per-project. A working_directory_mappings block keyed by absolute project path. Anything you set under a path applies only when Friday is run from that project. The base branch saved by /base-branch is the most common per-project override; worktree sync entries are another.

When the same key is set in both layers, the per-project value wins. If a key isn't set per-project, Friday falls back to the user-global value, then to the built-in default.

Common adjustments

A short list of settings most people touch. See each linked page for the details, and the Settings reference for the full schema.

Editing the file safely

A few habits keep manual edits painless:

  • Back up before bulk edits. cp ~/.friday/.user_preferences.yaml ~/.friday/.user_preferences.yaml.bak takes a second and saves you from having to remember what was in there.
  • Watch for YAML errors. If Friday refuses to start after a manual edit, the YAML is almost certainly malformed. Run a YAML linter or python -c "import yaml,sys;yaml.safe_load(open(sys.argv[1]))" ~/.friday/.user_preferences.yaml to find the bad line.
  • Restart after direct edits. Changes made through /settings are picked up live; changes made by editing the file are not guaranteed to be. Restart Friday to be sure.
  • API keys are not here. Friday's proxy auth uses gh auth token, so the credential path is gh auth login, not editing this file. See Installation.

Read next