Skip to main content

Advanced: Config File

A handful of TermFlow settings have no switch in the Settings window and can only be changed by editing the on-disk config file. This page lists those keys, their defaults, and where the file lives on each OS.

info

Everything on this page is optional. The Settings window covers all the day-to-day options (Appearance, Terminal Behavior, Shell Profiles, Connections). The keys below are for power users who want to tweak something the UI does not expose yet.

Where the config file lives​

TermFlow stores its settings in a single JSON file inside your operating system's per-user application config directory, in TermFlow's own app config folder.

OSBase directoryConfig file
Windows%APPDATA%%APPDATA%\<TermFlow config folder>\config.json
macOS~/Library/Application Support~/Library/Application Support/<TermFlow config folder>/config.json
Linux~/.config~/.config/<TermFlow config folder>/config.json

The file is created automatically on first run, when TermFlow also generates your auth token and writes the default values.

Dev and production use separate files

A production install reads and writes config.json. A development build (running from source via tauri dev) uses config.dev.json in the same folder, so a dev session and an installed copy never overwrite each other's settings — or collide on ports. Edit the file that matches the build you actually run.

Edit safely​

The app reads these values at launch and writes the file back whenever settings change. If you edit the file while TermFlow is running, your changes can be overwritten.

Quit before you edit
  1. Fully quit TermFlow.
  2. Open config.json in a text editor.
  3. Make your changes, keeping it valid JSON.
  4. Relaunch TermFlow.

Config-file-only settings​

These keys have no corresponding control in the Settings window. All keys are camelCase; add them at the top level of the JSON object.

KeyTypeDefaultWhat it does
fontFamilystring (CSS font stack)Consolas, "Courier New", monospaceThe terminal font. A standard CSS font-family list — the first installed font wins, later entries are fallbacks.
cursorStyleblock | underline | barblockShape of the text cursor.
cursorBlinkbooleantrueWhether the cursor blinks.
scrollbacknumber (lines)1000How many lines of history each terminal keeps for scrolling back.
restoreLastSessionbooleantrueOn launch, restore the previous session's tabs, panes, and scrollback. Set to false to always start with a clean, empty window.
theme / defaultThemeobjectbuilt-in dark themeA low-level ANSI color theme (background, foreground, cursor, selection, and 16 ANSI colors). See the note below before using it.

Example config.json​

{
  "fontFamily": "JetBrains Mono, Consolas, \"Courier New\", monospace",
  "cursorStyle": "bar",
  "cursorBlink": false,
  "scrollback": 5000,
  "restoreLastSession": true
}

Only include the keys you want to change — anything you omit falls back to its default.

Notes on individual keys​

  • fontFamily — Use a monospaced font for correct column alignment. Because it is a CSS font stack, you can list several fonts separated by commas; quote any name that contains spaces (as shown with "Courier New" above). Font size is not here — it has a slider in Settings → Appearance.
  • scrollback — Larger values keep more history at the cost of memory per terminal. This controls the scrollable history in the viewport; it is independent of session recording, which captures a session to a file.
  • restoreLastSession — When true (the default), TermFlow reopens your previous tabs and panes on the next launch. Set it to false if you prefer every launch to start empty.

An honest note: The theme / defaultTheme object is a low-level color override intended for internal use, and TermFlow does not validate it. For changing terminal colors, prefer the Color Schema picker in Settings → Appearance — it ships 24 ready-made schemes and applies live without a restart. Reach for the raw theme object only if you know exactly which fields you are setting.

What else is in this file​

The same config.json also holds your network settings — API port, MCP port, "Expose on local network", and your authToken — under a network object. Those all have proper controls in Settings → Connections, so manage them there rather than by hand.

Do not hand-edit the auth token

Your authToken is the real credential for the local API when the server is exposed on your LAN. If you need a new one, use the Rotate button in Settings → Connections — it swaps the token without a server restart and keeps existing UI connections alive. Never paste a token into a commit, log, or chat.

Next steps​