Configuration

Portable settings live in config.yaml. Machine identity and credentials stay next to the database, not in that file, so the YAML can be copied or committed.

version: 2
disable_auto_migrate: false
sync:
  enabled: false
  interval: 5m
  gc_interval: 1h
  rclone_engine: embedded
  endpoints: []
  callbacks: []
daemon:
  compact_interval: 5m
  config_watch_interval: 30s
suggest:
  enabled: true
  menu: false
  menu_max: 8
  completions: false
  accept:
    - Right
pty_proxy:
  enabled: false
  height: 100

Editors that speak YAML language servers can load config.schema.json:

# yaml-language-server: $schema=https://remnix.app/config.schema.json

remnix writes that comment when it saves. Unknown YAML keys are rejected (additionalProperties: false). A pre-v2 file with sync.transport or the old nested sync.rclone object is refused; run remnix setup.

Interactive changes: remnix config, remnix config sync, and remnix remote .... The configuration wizard saves only on success.

Files

Defaults follow XDG. Override the directories with environment variables; filenames inside them are fixed.

A leftover rclone.conf under the config directory is moved into the data directory on startup. Do not copy local.yaml to another machine; that device needs its own id. See rclone for where encrypted objects live on remotes.

Reload

The daemon reloads config.yaml on SIGHUP, remnix daemon reload, or when the file’s mtime changes (polled every daemon.config_watch_interval). Sync interval picks up immediately.

Ignore files are not part of that YAML watch. Recording re-reads them when their mtime or presence changes, so new ignore rules apply to the next command without a daemon restart.

Shell-generated glyphs and hooks come from remnix init. After changing ui colors/icons, suggest, or pty_proxy, re-source init (or start a new shell). Installing a new binary is not enough.

version and migrations

sync

Encrypted history synchronization. Details of bundles, checkpoints, and equalize are in the sync protocol. Provider-specific rclone notes are in rclone.

remnix sync uses every enabled endpoint; remnix sync --endpoint=<id> targets one. remnix remote add appends; it does not replace existing endpoints or mint a new Sync Master Key.

Endpoints

Each endpoint needs a unique id and a type. name is the display label (falls back to id). enabled opts it out of sync without deleting it.

Paths in path (and other user-supplied location strings) keep $HOME, ${VAR}, and ~/ as written. remnix expands them when the path is used, not when the file is saved.

sync:
  enabled: true
  rclone_engine: embedded
  endpoints:
    - id: google-drive
      type: rclone
      name: Google Drive
      rclone_remote: remnix-google-drive
      provider: google-drive
      path: remnix
      enabled: true
    - id: local-mirror
      type: directory
      path: ~/src/remnix-backup
      enabled: false

On S3/GCS the first path component is the bucket. Callbacks that run an external rclone sync against a directory endpoint still work; they are not the native rclone transport.

daemon

Background cadences for the long-lived remnix daemon.

remnix daemon compact runs the same cache prune on demand.

suggest

Inline history completion (ghost text) and the suggestion menu. Ranking is unchanged by these keys: match quality, recency, frequency, cwd, device, and session.

Ghost text still previews the best history match. History is not listed in the dropdown; completions sit under the typed row. Capture stops at 512 matches so a huge path completion cannot freeze the prompt.

When a CLI has no dedicated completer, overlay names (subcommands and flags) and descriptions come from parsed --help via suggest-cache.db. A new session does not re-run --help when the page is already cached. remnix suggest cache warmup aws gcloud starts a background walk into that file (a second warmup while one is running is queued onto the same worker). remnix suggest cache warmup --status attaches to live per-page progress. remnix suggest cache purge aws gcloud drops stale tools after a CLI upgrade.

pty_proxy

Unix only (Linux, macOS, WSL). Windows widgets use the alt-screen.

Put eval "$(remnix init ...)" near the top of the rc file so only the proxy re-execs. Set REMNIX_PTY_PROXY_LEGACY=1 to use the old per-terminal remnix pty-proxy process. Without a daemon session, widgets fall back to a local remnix search --interactive TUI.

Smaller heights still keep at least five history rows plus header, rule, help, and input.

ui

Colors and icons for the TUI. Empty values and the string default use the built-in Catppuccin-like theme. Hex must be #RGB or #RRGGBB. Ready-made palettes are on themes.

ui.colors

ui.colors.syntax

Command highlighting in search and inspect.

ui.icons

Ignoring commands

Optional sidecar files next to config.yaml skip recording. They do not delete or hide rows already in history.db, and they do not filter search, suggestions, inspect, or inbound sync. A command skipped at start still gets a UUID so the shell end hook is a no-op.

Both files are optional. Empty lines are skipped. Surrounding whitespace is trimmed. There are no # comments: a line is a pattern or it is empty. Matching either file is enough (OR).

ignore-commands.txt

One exact full command per line. ls skips ls, not ls -la.

ls
ll
exit

ignore-commands.regex

One Go RE2 pattern per line. The command is skipped if MatchString succeeds on the raw command (not anchored unless the pattern says so). Invalid lines are skipped with a warning so the rest of the file still applies.

^sudo
^rm -rf

Built-in secret skips

Regardless of those files, remnix never records a command whose text contains (case-insensitive):

• REMNIX_RECOVERY_KEY=
• RCLONE_CONFIG_PASS=
• AWS_SECRET_ACCESS_KEY=
• AZURE_STORAGE_KEY=

Prefer typing the recovery key interactively. Putting it on the command line is still visible in the original shell histfile.

Import (remnix import histfile / atuin) uses the same skip rules for new inserts. Existing rows are left alone.

Commands

Further reading: configuration wizard, rclone, architecture, themes.