Global Configuration

Flint keeps three configuration layers:

the configuration of each Flint in flint.toml
Flint-specific machine-wide configuration in ~/.nuucognition/flint/config.toml
the identity of this machine in the NUU config, ~/.nuucognition/config.toml

This guide shows the two machine-wide layers. It shows where each value lives, how to read it, and how to change it.

Prerequisites

Flint is installed and this machine is set up. See Setting Up a Machine.

The NUU Home

The NUU home holds everything that belongs to this machine. The default path is:

~/.nuucognition

It holds the NUU config, the Flint CLI config, the roster of Flints, the credential files, the failure records of flint fix, and the machine records.

The variable NUU_HOME selects another home. A command that runs with NUU_HOME=<dir> reads and writes its home in <dir> and leaves the real home alone. So a test can use a home of its own:

NUU_HOME=/tmp/test-home flint whoami

With NUU_HOME set, Flint also isolates Obsidian. Flint contacts no live Obsidian. It uses the vault registry <dir>/obsidian/obsidian.json, not the real one. Each skip prints the notice Obsidian: skipped (NUU_HOME isolation; live Obsidian not contacted). The Obsidian payload still installs into .obsidian/ of each Flint. NUU_ALLOW_LIVE_OBSIDIAN=1 allows the live contact and uses the real vault registry. Use it for live tests only.

The NUU Config

The NUU config is the shared file:

~/.nuucognition/config.toml

Every NUU CLI reads it. flint setup writes it once per machine. It holds the identity of this machine:

name: your Name. It is the author of your notes.
machine-display-name: the machine display name. It is the name that people read, such as "Ada Laptop".
machine-slug: the machine name, the short word of this machine in addresses, such as ada-laptop. It comes from the machine display name. A rename keeps it.
machine-name: the branch prefix of this machine. When it is not set, the hostname is the default.
default-org and default-org-id: the org of this machine. Each new Flint gets it.

A NUU account and an org are optional. Flint works with no NUU account and no org.

How to Read the Identity

Show the full identity of this machine:

flint whoami

Read one value:

flint config name
flint config machine-name
flint config org show

Each command with no value shows the stored value. Each of the three accepts --json for script use.

How to Change the Identity

Set the whole identity of this machine:

flint setup

Change your Name only:

flint config name "Your Name"

Change the branch prefix only:

flint config machine-name "main"

flint config name and flint config machine-name accept --unset to remove the stored value. After flint config machine-name --unset, the hostname is the default again.

The machine display name and the name of the Computer Flint are one name. To change the machine display name, rename the Computer Flint: run flint rename "<name>" in it. flint setup --machine-proper-name "<name>" does the same rename from any folder. The name uses letters, digits, and single spaces. The word computer is refused. The machine name stays the same. See Setting Up a Machine > Rename the Machine.

Set the org of this machine:

flint config org set <slug>

The id comes from --id <uuid>, from the enrollment of this machine, or from a Flint of that org on this machine. When this machine knows the org, --id is not needed. When the id is not known, the command stops and names the next command. The word none is not an org: to remove the org of this machine, run:

flint config org unset

After the unset, new Flints are local. The Flints, the enrollment, and the account do not change. See Join Your Org.

flint config org map <slug> <github-owner> writes one table [orgs.<slug>] in the NUU config. It maps a GitHub owner to an org. flint migrate run reads it for the shard records that the shard registry does not know.

The Flint CLI Config

The Flint CLI config file is:

~/.nuucognition/flint/config.toml

A dev build of the CLI uses ~/.nuucognition/flint-dev/config.toml. If the file does not exist yet, Flint falls back to in-memory defaults.

The file is a free key-value TOML file. flint config reads and writes these keys:

update-check: the daily release check. on is the default. off stops the check and its notice on this machine. The file holds it as update-check.
obsidian: the machine choice of Obsidian. on is the default. off says that this machine does not use Obsidian. The file holds it as [obsidian] choice.
obsidian-trust: community-plugin trust. auto is the default: flint open trusts a Flint that passes the trust check. ask shows the trust screen of Obsidian for each new vault. The file holds it as [obsidian] trust.

Flint also reads two tables of this file:

[obsidian.applied]: the machine layer of the applied settings of Obsidian. This layer is always in ~/.nuucognition/flint/config.toml, also for a dev build. Write it with flint obsidian applied set <file>.<key> <value> --machine. See Using Obsidian.
[orbit] devOrigins: the exact origins of dev Orbit servers, for example ["http://localhost:5173"]. The Flint server adds them to the origins that it authorizes. It reads this key from flint/config.toml and from flint-dev/config.toml. The key [server] dev-origins of flint.toml authorizes nothing, because Git shares flint.toml.

How to Inspect the Flint CLI Config

Show the whole config:

flint config

Read a single value:

flint config get obsidian
flint config get update-check
flint config get obsidian-trust
flint config get orbit.devOrigins

flint config get prints on or off for obsidian and update-check, and auto or ask for obsidian-trust. For another key that is not set, it prints <key> is not set.

Open the file in your editor:

flint config open

How to Change the Flint CLI Config

Set a value:

flint config set update-check off
flint config set obsidian on
flint config set obsidian-trust ask

update-check takes only on or off. obsidian takes only on or off. obsidian-trust takes only auto or ask. Another value stops the command, and it writes nothing.

flint config set reads the value as JSON when it can, else as text. Give an array or an object as a JSON string. A dotted key is a nested table. The command keeps every other key and every comment of the file. For example, this command writes devOrigins in [orbit]:

flint config set orbit.devOrigins '["http://localhost:5173"]'

flint config set refuses every key under obsidian. and names the command to use instead:

The machine choice goes through flint config set obsidian on|off.
The trust setting goes through flint config set obsidian-trust auto|ask.
An applied setting goes through flint obsidian applied set <file>.<key> <value> --machine.

See Using Obsidian.

The Daily Release Check

Once a day, a command in a terminal starts one background check: flint update --check --background. The check asks the npm registry for the newest Flint. It also compares the local Orbh profiles (default.json) with the file of the shared profiles repository. A later command prints one line for each newer item, at most once a day. Nothing installs by itself.

The check keeps its state in the cache folder of the system, not in the NUU home. It never runs in a pipe, with --json, in CI, in an Orbh session, for flint update and flint setup, or on a machine that is not set up.

To turn the check off on this machine:

flint config set update-check off

FLINT_NO_UPDATE_CHECK=1 turns it off for one shell or one command. See Setting Up a Machine > The Daily Release Check.

What Belongs Where

Use global config for:

how Flint behaves on your machine
whether this machine uses Obsidian
your Name, the machine names, and the org of this machine, through the NUU config commands

Use flint.toml for:

what the Flint is
what the Flint depends on
what the Flint publishes

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