Quick Start: Your First Flint

Get from zero to a working Flint workspace.

Prerequisites

• Node.js 20+ - Check with node --version
• macOS or Linux (Windows users: use WSL)
• Obsidian (optional but recommended) - For the best editing experience

Step 1: Install the CLI

Install Flint using the install script:

curl -fsSL https://raw.githubusercontent.com/NUU-Cognition/flint/main/install.sh | bash

This downloads the latest release and installs it to ~/.nuucognition/flint/.

Verify installation:

flint --version

Update

To update to the latest version, run the same command:

curl -fsSL https://raw.githubusercontent.com/NUU-Cognition/flint/main/install.sh | bash

Uninstall

rm -rf ~/.nuucognition/flint
sudo rm /usr/local/bin/flint  # or ~/.local/bin/flint

Your data (~/.flint/) is preserved.

Step 2: Create Your First Flint

Navigate to where you want your workspace and create a new Flint:

flint init "My Project"

This creates the folder (Flint) My Project/ with the essential structure.

Using a preset (recommended for new users):

flint init "My Project" --preset default

The default preset includes common plugins like projects, increments, and notepad.

Step 3: Explore the Structure

Navigate into your new Flint:

cd "(Flint) My Project"

Here's what was created:

(Flint) My Project/
├── flint.toml           # Configuration file
├── flint.lock           # Computed state (auto-generated)
├── .flint/              # Runtime data (gitignored)
├── Mesh/                # Your notes go here
│   └── (System) Flint Init.md
├── Imports/             # Content from other Flints
├── Exports/             # Compiled outputs for sharing
├── Workspace/           # Links to external resources
├── Media/               # Images, PDFs, assets
└── Plugins/             # Automation capabilities

If you used --preset default, you'll also see plugins installed in Plugins/.

Step 4: Read the Init File

Open Mesh/(System) Flint Init.md in any text editor. This file:

• Explains what this Flint is for
• Describes the folder structure
• Lists installed plugins
• Provides guidance for AI agents working in this space

Every time you (or an AI agent) starts working in a Flint, reading the init file first ensures you understand the workspace context.

Step 5: Open in Obsidian

For the best editing experience, open your Flint folder directly in Obsidian as a vault:

1. Open Obsidian
2. Click "Open folder as vault"
3. Select your (Flint) My Project/ folder

Flint's conventions (wiki-links, YAML frontmatter, folder structure) are fully compatible with Obsidian's features.

Step 6: Create Your First Note

Create a file in Mesh/. You can use the command line, your editor, or Obsidian.

Example note at Mesh/Project Ideas.md:

---
id: auto-generated-by-sync
tags:
  - "#brainstorm"
---

# Project Ideas

Initial thoughts for the project.

## Mobile App

A mobile companion would help with [On-the-Go Access](/on-the-go-access).

## Integration

Consider connecting to [External Services](/external-services).

Key concepts:

• Frontmatter - YAML at the top with metadata
• Wiki links - [Note Name](/note-name) links to other notes
• Tags - Use #tag format in frontmatter or inline
• IDs - Auto-generated by sync (unique identifiers)

Step 7: Sync Your Workspace

Run sync to update the workspace state:

flint sync

Sync performs several operations:

• Adds unique IDs to files that don't have them
• Installs/updates plugins declared in flint.toml
• Updates the index in .flint/

Run sync regularly - after adding notes, changing configuration, or when plugins need updating.

Step 8: Basic Workflows

Add Plugins

Edit flint.toml to add plugins:

[flint]
name = "My Project"
type = "flint"

[plugins]
required = [
  "core",
  "living-documents",
  "increments",
  "projects"
]

Then sync to install them:

flint sync

List Installed Plugins

flint plugin list

To see all available plugins:

flint plugin list --available

Link a Codebase

If your Flint relates to a codebase, create a workspace reference:

flint workspace add monorepo --type codebase
flint workspace fulfill monorepo /path/to/your/code

This creates Workspace/References/rf-monorepo.md documenting the link.

Index Your Notes

To manually rebuild the index:

flint index

This scans all markdown files and updates .flint/index.json.

Essential Commands Reference

File Naming Conventions

Flint uses typed prefixes to indicate document purpose:

Example: (Task) Implement Auth.md, (System) Flint Init.md

What's Next?

You now have a working Flint workspace. Here's where to go from here:

Learn More

• Guide - Core Concepts - Understand the mental model
• Guide - Introduction - The philosophy behind Flint
• Reference - CLI Commands - Complete command reference

Try the Tutorials

• Guide - Tutorial Project Planning - Plan a project with tasks and increments
• Guide - Tutorial Research Notes - Organize research with linked notes
• Guide - Tutorial Agent Collaboration - Work effectively with AI agents

Explore Modules

• Module - Mesh - Deep dive into your notes system
• Module - Plugins & Mods - Extend with automation
• Module - Workspace - Connect to external resources

Configuration

• Reference - Configuration - Global and workspace settings
• Guide - Global Configuration - Set up your preferences
• Guide - Registry Management - Manage your Flint collection

Troubleshooting

"Command not found: flint"

• Make sure the install completed successfully
• Check if ~/.local/bin is in your PATH
• Try: export PATH="$HOME/.local/bin:$PATH"

"Not inside a Flint"

• Make sure you're in a folder with flint.toml
• Navigate into the (Flint) Name/ folder, not its parent

Obsidian doesn't see the folder

• Use "Open folder as vault" in Obsidian
• Point it to the (Flint) Name/ directory

Sync shows errors

• Run flint repair to fix common issues
• Check flint.toml for syntax errors

For more troubleshooting, see Reference - Troubleshooting.