Setting Up a Machine

flint setup prepares a machine in seven steps. Run it once per machine. It needs internet access.

flint setup

Prerequisites

You need:

• a terminal on macOS or Linux
• internet access
• Node.js 26.1 or newer, with npm
• the Flint CLI: npm install -g @nuucognition/flint-cli
• no NUU account and no org (both stay optional)

Setup checks Git, Obsidian, and the agent CLIs in step 3. A missing tool does not stop the setup.

Set Up With an Agent

An agent can do the setup with you. Run the install script in a terminal:

curl -fsSL https://flint.nuucognition.com/install.sh | bash

The script checks the OS and Claude Code. It installs nothing. It starts Claude Code with the setup procedure of https://flint.nuucognition.com/setup.md. The agent asks you before each change to the machine. It installs Flint, runs flint setup, and writes a handoff file. Then it starts the onboarding session with that handoff:

flint setup handoff check <file>                         # Check a handoff file (spec flint-setup-handoff/0.1); write nothing
flint setup onboard --handoff <file> --target claude     # Start the onboarding session that reads the handoff note first

The handoff note is Mesh/(System) Setup Handoff.md in the Computer Flint. The rest of this page is the manual path.

The Network Check

Setup checks the network before the first step. With no network, it stops. It asks nothing and writes nothing.

Flint setup needs internet access. Connect to the internet, then run flint setup again.

The Seven Steps

Each step prints a header, such as Step 2 of 7 - Git author. A summary ends the run.

Step 1: Identity

Setup asks two questions: your Name and the machine display name. Press Enter to keep a default.

• Your Name is how you appear as the author of notes on this machine.
• The machine display name is the name that people read, such as "Ada Laptop".
• The machine name is the short word for this machine in addresses. It comes from the display name.
• The branch prefix comes from the hostname. flint setup --machine-name <word> changes it.

The answers go into the NUU config (config.toml in the NUU home, ~/.nuucognition). Every NUU CLI reads them.

flint setup --name "Ada Lovelace" --machine-proper-name "Ada Laptop"

Step 2: Git Author

Setup shows the Git author. When Git has no email, it asks for one.

Each new Flint is a Git repository with a first commit. Git needs an author for that commit.

flint setup --git-email "ada@example.com"

The flag answers the email question. Git keeps an email that it has. The Git author name is your Name.

Setup never replaces a Git author value. When Git cannot read a key of the global Git config, the step asks nothing and writes nothing. The summary then shows a warning that ends with Setup wrote nothing.

Step 3: Environment

Setup checks the tools of this machine: Git, Node.js, Obsidian, and the agent CLI of each target of the default target list.

A missing tool shows ✘ with its install command. A missing tool never stops the setup.

Then setup checks the terminal font JetBrainsMono Nerd Font. The Obsidian terminal uses this font to show the glyphs of the agent titles. When the font is missing, setup asks Install the font JetBrainsMono Nerd Font? (the default is yes). It installs the font with Homebrew on a Mac that has Homebrew, else from the release zip of Nerd Fonts.

• --font and --yes install the font with no question.
• --no-font, the answer "no", and no terminal skip the font.
• With no network, or when the install fails, setup gives a warning.
• Each skip and each failure prints Later: flint setup font.
• With NUU_HOME set, setup installs no font.

Step 4: Agent Default

Setup copies the Orbh profiles first. When the Orbh home has no default.json, setup copies it from the public repository NUU-Cognition/orbh-profiles. The screen shows Copying the Orbh profiles while it works. Setup never writes profiles.json, the file of the person. With no network, or when the copy fails, setup gives a warning and prints Later: flint orbh profiles update.

Then setup shows the default target list and the target that Orbh selects now. In a terminal, you can put another target first. Setup writes that order to the machine layer.

Step 5: Computer Flint

Setup makes the Computer Flint when it is missing. It asks no question.

When setup cannot make the Computer Flint, the run fails. The screen names the repair command.

Step 6: Guide

Setup clones the Guide of NUU Cognition into the home folder, beside the Computer Flint. The folder is (Guide) NUU Cognition. The Guide is a public Flint from https://github.com/NUU-Cognition/guide-nuu-cognition. Its shard Flint Help answers Flint questions and explains Flint problems. You ask it with an agent. The summary of setup names the command:

flint orbh i -p ~/"(Guide) NUU Cognition"

Setup asks Clone the Guide? The answer "yes" is the default. Setup skips the clone in four cases:

• with --no-guide
• when you answer "no"
• with no terminal and neither --guide nor --yes
• with no network

Each skip prints Later: flint setup guide.

Step 7: Open and Onboarding

Setup opens the Computer Flint in Obsidian on every run. The first open of a machine has one trust click ("Trust author and enable plugins"). Obsidian then reloads once, and the onboarding session starts in a terminal tab after that reload.

A later run resumes the recorded onboarding session. The session explains Flint and helps you make the first Flint.

• With --no-open, with Obsidian off, or with no Obsidian, the session runs in the terminal after the summary.
• With NUU_HOME set, the step opens nothing.
• With --json or no terminal, setup starts no session. The summary names flint setup onboard.

The Flags

flint setup --yes
flint setup --no-guide --no-open

The flags --computer and --no-computer are retired. Each prints one line, and the run continues. Setup always makes the Computer Flint.

A Second Run

A second run asks nothing that is stored. It keeps the Computer Flint and the Guide. It opens the Computer Flint and resumes the onboarding session.

Only three things fail a run: step 1, step 5, and a stop (Ctrl-C). Each other step gives a warning and a Later: line.

The Computer Flint

The Computer Flint is the home of this machine. One machine has one. It is a Flint of the type computer.

It holds the "Start here" note, its system note, and the repair notes of flint fix. See Doctor and Fix.

Where It Lives

Its folder is (Computer) <Machine Display Name> in the home folder, for example ~/(Computer) Ada Laptop. With NUU_HOME set, it lives in the folder above the NUU home.

It is a local Git repository with no remote. It is private to this machine.

The Reserved Word

The word computer names the Computer Flint. It works from any folder.

flint open computer
flint cd computer

No other Flint can take the word as its name, local name, or alias. With no Computer Flint, the word refuses with Next: flint setup computer.

Make It Alone

flint setup computer

The command makes the Computer Flint alone. It never converts a Flint that exists. --dry-run says what it would do and changes nothing.

Rename the Machine

The machine display name and the name of the Computer Flint are one name. Two commands rename both together:

flint rename "<name>"                        # In the Computer Flint
flint setup --machine-proper-name "<name>"   # From any folder

The rename moves the folder, the roster row, and the Obsidian vault entry together. The machine word of addresses stays the same.

Move It

flint move computer "<new path>"

The command moves the Computer Flint and updates the roster. The claim follows, so Flint still finds it. Do not move the folder by hand.

The Guide Alone

flint setup guide

The command clones the Guide of NUU Cognition alone. A present Guide stays: the command finds it by its Flint id and clones nothing.

To get the newest Guide later, run flint git merge in the Guide. It takes the new history from origin and runs the local sync. It pushes nothing. Do not run flint git sync in the Guide: it tries to push to the public repository.

The Terminal Font Alone

flint setup font

The command installs the terminal font JetBrainsMono Nerd Font alone. flint doctor shows the font on its row Terminal font.

The Onboarding Session Alone

flint setup onboard

The command starts or resumes the onboarding session in the Computer Flint. It opens in an Obsidian terminal tab when Obsidian can open. Else it runs in the terminal.

flint setup onboard --print     # Show the plan and write nothing
flint setup onboard --no-open   # Run in the terminal, with no Obsidian

With no Computer Flint, the command refuses with Next: flint setup.

The Daily Release Check

Once a day, a command in a terminal starts one background check. It asks the npm registry for the newest Flint. It compares the shared Orbh profiles with the local file. The command never waits for the network.

A later command prints one line for each newer item, at most once a day:

Flint 0.8.0 is available (this machine has 0.7.0). Next: flint update
Newer Orbh profiles are available. Next: flint orbh profiles update

Nothing installs by itself. No check runs in a pipe, with --json, in CI, in an agent session, for flint update and flint setup, or on a machine that is not set up.

To turn the check off:

flint config set update-check off

FLINT_NO_UPDATE_CHECK=1 turns it off too.

Update Flint

flint update

The command installs the newest release of Flint. It compares versions, so it never installs an older version.

flint update --check           # Name the newest release; install nothing
flint update --check --json    # The same, as one JSON value

A Flint that is a build of a checkout installs nothing. Update the checkout, then build it.

Next Steps

• Quick Start — from the install to the first Flint
• Join Your Org — log in, set your org, and share Flints
• Creating a Flint — presets, org, and options
• The Roster — the list of Flints on this machine
• Using Obsidian — the Obsidian payload and trust
• Doctor and Fix — check the machine and repair failures
• CLI Commands — the full command list