Quick Start: Your First Flint

This guide takes you from the install to your first Flint and your first agent session. You need no NUU account and no org.

Prerequisites

You need:

macOS or Linux, with a terminal where global npm installs are allowed
Node.js 26.1 or newer, with npm (an older Node.js stops flint with one line that names the version)
Git
internet access for the setup
Obsidian, if you want it (it is optional). On Linux, use the AppImage or the .deb of Obsidian. Flint does not open a Flatpak or a Snap Obsidian.
an agent CLI, if you want agents: Claude Code (claude) or Codex (codex)

You do not have to check these tools yourself. flint setup checks them and gives the install command for each tool that is missing.

An agent can do Steps 1 and 2 with you: curl -fsSL https://flint.nuucognition.com/install.sh | bash starts Claude Code with the setup procedure. See Setting Up a Machine > Set Up With an Agent.

Step 1: Install the CLI

npm install -g @nuucognition/flint-cli
flint --version

The package installs two commands: flint and nuu. You type flint. nuu manages the identity of this machine and the network; most people never type it.

On a new machine, flint with no command starts flint setup in a terminal. With no terminal, it names the first step and exits 0:

Flint is not set up on this machine. Start with: flint setup
It sets your Name, checks the tools of this machine, selects the agent default, and makes your Computer Flint.
Or create a Flint now: flint create "<name>" (it asks your Name first).

Common commands: create, list, open, sync, shard, whoami, status. All commands: flint --help

To see if a newer release exists later:

flint update --check

Step 2: Set Up This Machine

flint setup

flint setup needs internet access. With no network it stops before the first step. It runs seven steps in order:

Identity: your Name and the machine display name.
Git author: the author of the first commits of new Flints.
Environment: a check of Git, Node.js, Obsidian, and the agent CLIs, and the terminal font JetBrainsMono Nerd Font (setup asks before it installs the font).
Agent default: the first copy of the Orbh profiles and the default target list.
Computer Flint: the home Flint of this machine. It holds the "Start here" note and the notes of the repair sessions. See The Computer Flint.
Guide: a clone of the Guide of NUU Cognition, a Flint that answers Flint questions with an agent (optional).
Open and onboarding: the open of the Computer Flint with your first agent session.

The one trust click. Obsidian asks you to trust the plugins of a new vault. At step 7, click Trust author and enable plugins in the Computer Flint. This is the only trust click on this machine. After it, flint open opens each new Flint with its plugins on, and Obsidian does not ask again. See Using Obsidian.

[!note] "Vault not found" at the first open Obsidian does not know the folder of the Computer Flint yet, so the first open can show "Vault not found". Then open Obsidian, choose Open folder as vault, and select the folder of the Computer Flint. Click Trust author and enable plugins. Later, flint open computer opens it.

After setup, flint with no command shows your Computer Flint and the next command, and exits 0:

Flint is set up on this machine.
Computer Flint: ~/(Computer) Ada Laptop

Next: flint create "<name>"
Optional: flint doctor

All commands: flint --help

With no Computer Flint, the second line is Computer Flint: none, and the block adds Later: flint setup computer.

Run flint setup again at any time. 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.

When Git has no author, flint create stops before it writes anything:

✘ Git has no author name (user.name) and no author email (user.email) on this machine. The first commit of the Flint needs a name and an email. flint setup sets them. Nothing was written.
  Next: flint setup
  Or:   flint create "My Notes" --no-git

You can also set the Git author yourself:

git config --global user.name "Ada Lovelace"
git config --global user.email "ada@example.com"

For the full detail of each step, read Setting Up a Machine. To change your Name only later, run flint config name "<Name>". If you skip setup, flint create asks for your Name first. Login and an org stay optional; to share Flints with an org, read Join Your Org.

Step 3: Create a Flint

flint create "My Notes"

flint create makes the folder (Flint) My Notes in the current folder. (flint init is an alias of flint create.) The screen tells you what you have.

✓ Created the Flint My Notes
  Address  : @/flint/my-notes (local: no org, this machine only)
  Path     : ~/notes/(Flint) My Notes
  Shards   : invironments, flint, orbh (preset blank)
  Git      : a local repository (no remote)
  Obsidian : payload 0.7.0 installed · opened
Next: flint open "My Notes"
Or start an agent: cd '/home/ada/notes/(Flint) My Notes' && flint orbh i
Later: flint git publish <url>

In a terminal, flint create installs the Obsidian payload and opens the Flint in Obsidian. After the trust click in your Computer Flint, the new Flint opens with its plugins on, and Obsidian does not ask.

On a machine with no Computer Flint, or when the NUU Flint plugin of the new vault does not answer, Obsidian asks once for the new vault. The Obsidian row then has one more line:

  Obsidian : payload 0.7.0 installed · opened
             Click "Trust author and enable plugins" once in Obsidian.

With --no-open, or with no terminal, Obsidian does not open, and the row says payload 0.7.0 installed · not opened. See Using Obsidian.

An address that starts with @/ names no org. It works only on this machine. To share the Flint, give it an org: flint org set <org>.

Useful variants:

flint create "My Notes" --preset default   # More shards: Projects, Notepad, Plan, Increments, Reports, Agents, Claude Code
flint create "My Notes" --path ~/notes      # Make the Flint in another folder
flint create --from <git url>               # Clone a Flint from a Git repository
flint create "My Notes" --no-obsidian       # Skip Obsidian for this run only

A preset is the list of shards of a new Flint. blank is the default: only the core shards (Flint and Orbh; Invironments comes with Flint). flint create --help lists the presets. For the full detail, read Creating a Flint.

If the network is down, flint create still makes the Flint. It names each part that it did not install, and it prints the one next command that installs the missing parts.

Step 4: Open the Flint in Obsidian

In a terminal, flint create already installs the Obsidian payload and opens the Flint in Obsidian (see Step 3). To open or focus the Flint later, run:

flint open "My Notes"

Flint needs no one editor: the files are plain Markdown. For the payload, the applied settings, and the backups, read Using Obsidian.

Now move into the Flint:

cd "(Flint) My Notes"

A new Flint holds Mesh/ for your notes, Media/ for files that are not Markdown, Shards/ for the programs that agents load, and Sources/, Workspace/, and .flint/ for outside material, active repositories, and the facts of this machine. It has no Modules/ folder and no env files. flint module install creates Modules/. You create the env files when the Flint needs them.

Open Mesh/(System) Flint Init.md. This note tells humans and agents what the Flint is for. A new Flint has a starter note; in the first agent session, the agent asks you what the Flint is for and rewrites the note.

Step 5: Add a First Note

Create a note in Mesh/:

---
id: 11111111-1111-1111-1111-111111111111
tags:
  - "#note"
authors:
  - "[[@Ada Lovelace]]"
---

# Project Ideas

Initial thoughts for the project.

## Goals

- Keep architecture notes close to the codebase
- Track follow-up tasks in one place

Give each note its own id (a new UUID). authors names you: @ and your Name (flint whoami shows it). Three habits help from the start: use frontmatter in each note, use tags on purpose, and link related notes with [[wiki links]]. An agent makes notes with the same shape: the Flint shard has the note template tmp-f-note-v0.1.

Step 6: Sync After a Change

When you change flint.toml, run:

flint sync

flint sync makes the files of this Flint match its lock and its declarations. It installs missing shard builds and the pinned Obsidian payload. It never reads the shard registry and never pushes or pulls Git. It only fetches each workspace repository and reports whether it is behind origin. To see the plan first, run flint sync --dry-run. For the full detail, read Sync.

When you add or change a shard spec in flint.toml, run flint shard install first. It makes the lock match the specs. To exchange history with origin, run flint git sync.

Step 7: Start an Agent Session

From inside the Flint, run:

flint orbh i

This starts an interactive agent session with Orbh session tracking. With no target, Orbh uses the default target list and selects the first target that can run. The list that Orbh ships is claude/o55h, then codex/a6h. Before the session starts, Orbh prints the target, and the reason for each target that it skipped:

claude/o55h skipped: claude is not installed
Target: codex/a6h (default list)

If no target can run, it prints the one install command that makes one available. flint orbh profiles default shows the list and the state of each target. An explicit target, such as flint orbh i codex/a6h, never falls back to another target. For the full detail, read Agent Sessions > The Default Target List.

When a Command Fails

When flint sync, flint create, flint git sync, flint shard install, flint setup, or flint tinderbox sync fails, its output ends with one more line:

  Or:   flint fix

flint fix starts a repair session: an agent in your Computer Flint that reads the failure and helps you repair it. The agent asks you before each change to the Git history, to the lock, or to flint.toml.

flint doctor checks this machine and the current Flint at any time. It starts no agent. Each failed check has one next command. See Doctor and Fix.

Next Steps

Setting Up a Machine — the seven setup steps in full detail
The Computer Flint — the home of this machine, its rename, and the repair notes
Creating a Flint — presets, types, clones, and the result rows
Join Your Org — log in, set your org, enroll this machine, and share Flints
Doctor and Fix — check this machine with flint doctor, and repair a failure with flint fix
Troubleshooting — the common problems and the next command for each
The Roster — the list of Flints on this machine
Using Obsidian — the Obsidian payload, applied settings, and backups
Agent Sessions — interactive sessions, targets, and profiles
Tutorial Project Planning
Tutorial Research Notes
Tutorial Agent Collaboration

Quick Start: Your First Flint

On this page