Quick Start: Your First Flint

This guide walks from install to a useful first workspace. The goal is not just to get Flint running, but to get you into the right habits from the start.

Before You Begin

You need:

Node.js with npm
a terminal where global installs are allowed
any text editor you like
Obsidian if you want the best vault-style editing experience, though it is optional

Step 1: Install the CLI

Install the CLI package:

npm install -g @nuucognition/flint-cli

Check that the binary is available:

flint --version

If you want to see whether a newer release exists later:

flint update --check

Step 2: Create a Workspace

Create a new Flint in the current directory:

flint init "My Project"

This is the default, cleanest starting point. Behind the scenes, Flint:

creates the workspace directory
writes flint.toml
writes flint.json
creates the standard subdirectories
registers the workspace in your local registry
runs flint sync

Useful variants:

flint init "My Project" --preset default
flint init "My Project" --path ~/workspaces
flint init --from-git git@github.com:owner/repo.git

When to use them:

--preset default when you want a more fully seeded workspace from the start
--path when your current directory is not where you want the Flint created
--from-git when the workspace already exists as a Flint repository elsewhere

Step 3: Move Into the Flint

cd "(Flint) My Project"

The base structure looks like this:

(Flint) My Project/
├── flint.toml
├── flint.json
├── .flint/
├── Mesh/
├── Media/
├── Shards/
├── Sources/
├── Exports/
└── Workspace/

That layout is worth learning early because it will shape everything you do next.

Mesh/ is where your actual thinking goes.
Shards/ is where the workspace keeps cognitive programs for agents.
Sources/ is for copied-in external context.
Workspace/ is for active repos that belong inside the workspace.
Exports/ is for built output.
.flint/ is for local runtime and fulfillment state.

Step 4: Read the Init Note

Open:

Mesh/(System) Flint Init.md

This file is not just a welcome message. It is the workspace contract for both humans and agents. A good init note answers:

what this Flint is for
what belongs in Mesh/
which shards matter here
what external systems the workspace depends on
how an agent should start working

If you skip this note, the workspace will feel more confusing than it needs to.

This is also where you make the workspace executable for an agent. The init note tells the agent which shard-based cognitive programs are relevant and how to apply them here.

Step 5: Add a First Note

Create something simple in Mesh/, such as:

---
id: 11111111-1111-1111-1111-111111111111
tags:
  - "#proj/note"
---

# Project Ideas

Initial thoughts for the project.

## Goals

- Keep architecture notes close to the codebase
- Track follow-up tasks in one place
- Export a clean public guide later

At this stage, focus on three habits:

use frontmatter consistently
use tags deliberately
start linking related notes with [wiki links](/wiki-links)

These habits matter because shards work best when an agent can read the workspace cleanly and write back into it predictably.

Step 6: Declare One Real Dependency

The biggest mistake new users make is treating a Flint like a self-contained notebook. Flint becomes much more useful once it is connected to something real.

If the workspace is about a codebase

Declare and fulfill a codebase reference:

flint reference codebase "Main App"
flint fulfill codebase "Main App" /path/to/app
flint reference list

Now the workspace has a named relationship to the code it is describing.

If the workspace needs read-only material from elsewhere

Add a source mesh export:

flint source meshexport list
flint source meshexport add "Research Hub/Guide"

If the workspace should contain an active repo clone

Create a workspace repo:

flint workspace create "App" git@github.com:me/app.git
flint workspace list

The distinction matters:

use references when the thing stays outside the workspace
use sources when you want copied-in read-only context
use workspace repos when the repo should live inside the Flint

That structure is what makes Flint a usable execution environment for shards. A cognitive program is much more reliable when the agent can clearly tell what is durable thinking, what is copied context, and what is active working code.

Step 7: Sync After Config Changes

Any time you meaningfully change flint.toml, run:

flint sync

flint sync is responsible for reconciling the workspace with the declarations you made. Depending on what is configured, it can:

ensure standard directories and state files exist
install or reconcile shards
bootstrap .obsidian/
synchronize source mesh exports
refresh metadata notes for sources and references
update .gitignore
refresh registry information

If Flint has a heartbeat, it is flint sync.

It is also the moment when declared cognitive programs become available in the workspace. If shards are the programs, sync is one of the main ways Flint makes sure the execution environment is ready for them.

Step 8: Build Something Shareable

If you want to publish a guide or report from the workspace, tag a root note with #export and run:

flint export scan
flint export build
flint export list

This is where Flint starts to feel different from a normal markdown vault. Notes are not only for internal thinking; they can also become built artifacts.

Step 9: Open the Workspace Comfortably

If you use Obsidian, you can open the folder directly there. You can also use:

flint open

The important point is that Flint does not require one specific editor. The files remain plain and portable.

A Strong First-Day Workflow

If you want a practical first-day loop, do this:

create the Flint
improve the init note
write two or three real Mesh notes
add one codebase reference or one source
run flint sync
tag one note with #export
run an export build

By the end of that sequence, you will have touched the main parts of the system in the right order.

Where to Continue

Once the workspace exists, choose the guide that matches the kind of work you actually want to do:

Quick Start: Your First Flint

On this page