Global Configuration

Flint has two different configuration layers:

• workspace configuration in flint.toml
• machine-wide configuration in the global config file

This guide is about the second one.

The Role of Global Config

Global config is for preferences and runtime behavior that belong to your machine, not to one particular Flint.

That distinction matters. If a setting should travel with the workspace when someone else clones it, it probably belongs in flint.toml. If it only affects how Flint behaves on your own machine, it probably belongs in global config.

Where It Lives

The global config file is:

~/.nuucognition/flint/config.toml

If the file does not exist yet, Flint falls back to in-memory defaults.

What Global Config Supports

Flint supports a deliberately small set of global fields:

• mode
• [open].apps

Example:

mode = "production"

[open]
apps = [
  "obsidian",
]

That small scope is a feature, not a limitation. It keeps the distinction between global preferences and workspace declarations clean.

How to Inspect Global Config

Show the whole config:

flint config

Read a single value:

flint config get open.apps

Open the file in your editor:

flint config open

How to Change Values

Set a simple value:

flint config set mode experimental

Set a JSON-style array:

flint config set open.apps '["obsidian"]'

The command attempts to parse JSON where appropriate, which is why arrays and objects should be passed as JSON strings.

Understanding mode

mode is part of Flint’s feature-gating system. Flint recognizes:

• production
• experimental
• dev

This setting matters because some parts of the CLI are only available in certain runtime modes. The clearest example is the runtime command group, which is dev-gated in the CLI entrypoint.

You do not need to change mode for everyday Flint usage. Most people can leave it alone unless they are intentionally working with gated or development-only features.

Understanding open.apps

open.apps stores a list of preferred applications for opening a Flint.

Flint stores this list globally, and the default config effectively behaves as:

[open]
apps = ["obsidian"]

Even if you only ever use one app, it is helpful to understand that this is a machine preference, not a workspace-level declaration.

What Should Not Go Here

Do not put workspace-specific structure or dependencies into global config. These belong in flint.toml instead:

• shard declarations
• references
• sources
• exports
• workspace repositories
• lattice declarations
• server port

If another person cloning the Flint needs the setting, it almost certainly belongs in the workspace config, not the global one.

A Good Rule of Thumb

Use global config for:

• how Flint behaves on your machine
• what apps you prefer
• what feature mode you intentionally run in

Use flint.toml for:

• what the workspace is
• what the workspace depends on
• what the workspace publishes

Keeping that line clean will save you a lot of confusion later.