CLI Reference: Complete Command Guide

Complete reference for all Flint CLI commands.

Overview

The Flint CLI provides workspace management commands for creating, syncing, and managing Flint workspaces. Commands auto-detect your workspace from the current directory.

flint <command> [options]

Core Commands

flint init

Create a new Flint workspace.

Usage:

flint init <name> [options]

Options:

Flag	Description	Default
`-p, --path <dir>`	Parent directory for the new Flint	Current directory
`--preset <name>`	Use a preset configuration	None

How it works:

Init creates the essential Flint structure, then runs sync to install configured features:

init:  name -> folder -> directories -> .flint/ -> flint.toml -> flint.json -> registry
sync:  migrations -> .obsidian -> shards -> mods -> imports -> workspace -> connections -> .gitignore

Available presets:

blank - Empty flint, no shards or mods (default when no preset specified)
default - All standard shards and mods

Examples:

flint init my-project                    # Empty flint (blank)
flint init research --preset default     # With all shards and mods
flint init docs --path ~/projects        # In specific directory

flint list

List all registered Flints.

Usage:

flint list [options]

Aliases: ls

Options:

Flag	Description	Default
`--json`	Output as JSON	false
`--full-path`	Show full paths instead of abbreviated	false
`-s, --status`	Show valid/broken status for each entry	false

Examples:

flint list                  # List all registered flints
flint list --status         # Show validity status
flint list --json           # JSON output for scripting
flint list --full-path      # Show complete paths

flint sync

Synchronize configuration with actual state. Installs shards, mods, and runs migrations.

Usage:

flint sync [options]

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect

What it does:

Creates missing directories
Runs pending migrations
Clones .obsidian/ configuration if missing
Installs/updates shards declared in flint.toml
Installs/updates mods declared in flint.toml
Pulls required imports
Validates workspace references
Updates registry if name/path changed
Validates and reports connection status
Updates .gitignore
Runs mod onSync hooks
Stamps sync timestamp in flint.json

Examples:

flint sync                  # Sync current workspace
flint sync --path ~/my-flint  # Sync specific workspace

flint index

Add unique IDs to markdown files in the Mesh. Each file gets a UUID in its frontmatter.

Usage:

flint index [options]

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect
`--dry-run`	Report what would change without modifying files	false
`-v, --verbose`	Log each file processed	false

Examples:

flint index                 # Index all markdown files
flint index --dry-run       # Preview changes
flint index --verbose       # See each file processed

flint delete

Permanently delete a Flint (removes folder and unregisters).

Usage:

flint delete [name-or-path]

Arguments:

[name-or-path] — Flint name or path (defaults to current directory)

Requires typing the Flint name as confirmation before deletion.

Examples:

flint delete                        # Delete current Flint
flint delete "Old Project"          # Delete by name
flint delete /path/to/flint         # Delete by path

flint repair

Repair a Flint to match current specifications.

Usage:

flint repair [options]

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect
`-n, --dry-run`	Show what would be fixed without making changes	false

What it checks:

Missing standard directories (Mesh/, Shards/, Mods/, etc.)
Missing flint.toml or flint.json
Missing registry entry
Missing or outdated .gitignore
Missing .obsidian/ configuration

Examples:

flint repair                        # Repair current Flint
flint repair --dry-run              # Preview what would be fixed
flint repair --path ~/my-flint      # Repair specific Flint

Shard System

flint shard

Manage Flint shards. Shards extend workspaces with context, skills, templates, workflows, and knowledge.

flint shard list

List installed shards.

Usage:

flint shard list [options]

Options:

Flag	Description	Default
`--sources`	Show source declarations from flint.toml	false
`-p, --path <dir>`	Path to Flint workspace	Auto-detect

Examples:

flint shard list               # Show installed shards with versions
flint shard list --sources     # Show source declarations

flint shard install

Install a shard from GitHub or a local path.

Usage:

flint shard install <source> [options]

Arguments:

<source> — Source reference (e.g., NUU-Cognition/shard-projects, path:./local/path)

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect
`-f, --force`	Overwrite existing files	false

What it does:

Clones the shard repository (if from GitHub)
Reads shard.yaml manifest
Auto-installs dependencies (circular deps prevented)
Creates the shard folder with all files
Creates declared folders in Mesh/
Installs files from install/ with template processing
Clones declared repos to Shards/(System) Repos/
Creates state file if configured
Adds declaration to flint.toml

Examples:

flint shard install NUU-Cognition/shard-projects         # From GitHub
flint shard install github:owner/repo                    # Explicit GitHub
flint shard install path:./Shards/(Dev) My Shard         # From local path
flint shard install NUU-Cognition/shard-projects --force  # Force overwrite

flint shard uninstall

Uninstall a shard.

Usage:

flint shard uninstall <name> [options]

What it does:

Removes the shard folder
Removes installed files, declared folders (if empty), and repos
Removes the flint.toml declaration

Examples:

flint shard uninstall Projects     # Uninstall by name

flint shard update

Update all installed shards from their remote sources. Dev shards are skipped.

Usage:

flint shard update [options]

Options:

Flag	Description	Default
`--reinstall`	Force re-download all shards	false
`-p, --path <dir>`	Path to Flint workspace	Auto-detect

Examples:

flint shard update              # Update all non-dev shards
flint shard update --reinstall  # Force re-download all

flint shard create

Scaffold a new dev shard for local authoring.

Usage:

flint shard create <name> [options]

Options:

Flag	Description	Default
`-s, --shorthand <sh>`	Shard shorthand identifier	Auto-generated
`-d, --description <desc>`	Shard description	Empty
`--setup`	Include a setup file	false
`--state`	Create state file	false

Examples:

flint shard create "My Shard" -s ms -d "My custom shard"

Creates Shards/(Dev) My Shard/ with standard structure and records in flint.toml with dev = true.

flint shard dev

Clone an existing shard for local development.

Usage:

flint shard dev <source>

Examples:

flint shard dev NUU-Cognition/shard-projects

Copies the resolved shard into Shards/(Dev) Name/ with dev = true.

flint shard check

Check shard system health.

Usage:

flint shard check

Reports issues with installed shards (missing files, broken dependencies, etc.).

flint shard heal

Fix issues in a specific shard.

Usage:

flint shard heal <name> [options]

Options:

Flag	Description	Default
`--dry-run`	Show what would be fixed	false

Examples:

flint shard heal Projects            # Fix issues
flint shard heal Projects --dry-run  # Preview fixes

flint shard reinstall

Reinstall a shard's install entries (files declared in shard.yaml).

Usage:

flint shard reinstall <name> [options]

Options:

Flag	Description	Default
`--force`	Overwrite existing files	false

Examples:

flint shard reinstall Projects          # Reinstall (respects once/force)
flint shard reinstall Projects --force  # Force overwrite all

flint shard scripts

List available scripts in a shard.

Usage:

flint shard scripts <name>

flint shard <name> <script>

Run a script from a shard.

Usage:

flint shard <name> <script-name> [args...]

Scripts run with the flint root as working directory and receive FLINT_ROOT and FLINT_SHARD environment variables.

Examples:

flint shard Projects newtasknum        # Run a script
flint shard Projects exec ls           # Run arbitrary command in shard dir

flint shard gitinit

Initialize git for a dev shard.

Usage:

flint shard gitinit <name> <url>

Examples:

flint shard gitinit my-shard https://github.com/org/repo.git

flint shard push

Push changes for a dev shard.

Usage:

flint shard push <name> -m <message>

Examples:

flint shard push my-shard -m "Add new skill"

flint shard pull

Pull/sync shard repos declared in shard.yaml.

Usage:

flint shard pull [name]

flint shard info

Show detailed information about a shard.

Usage:

flint shard info <name>

flint shard add

Add a shard declaration to flint.toml without installing it.

Usage:

flint shard add <source>

flint shard remove

Remove a shard declaration from flint.toml only (does not uninstall files).

Usage:

flint shard remove <name>

flint shard register

Usage:

flint shard register <folder>

flint mod

Manage Flint mods (environment modifications like Claude Code support).

flint mod list

List installed mods.

Usage:

flint mod list [options]

Options:

Flag	Description	Default
`--sources`	Show source declarations from flint.toml	false
`-p, --path <dir>`	Path to Flint workspace	Auto-detect

Examples:

flint mod list                  # Show installed mods
flint mod list --sources        # Show source declarations

flint mod install

Install a mod from GitHub or a local path.

Usage:

flint mod install <source> [options]

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect
`-f, --force`	Overwrite existing files	false

Examples:

flint mod install NUU-Cognition/flint-mod-claude-code         # From GitHub
flint mod install path:./Mods/(Dev) My Mod                    # From local path
flint mod install NUU-Cognition/flint-mod-claude-code --force # Force overwrite

flint mod uninstall

Uninstall a mod.

Usage:

flint mod uninstall <name> [options]

Examples:

flint mod uninstall claude-code     # Remove mod

flint mod update

Update all installed mods from remote sources. Dev mods are skipped.

Usage:

flint mod update [options]

Examples:

flint mod update                # Update all non-dev mods

flint mod create

Scaffold a new dev mod for local authoring.

Usage:

flint mod create <name> [options]

Options:

Flag	Description	Default
`-s, --shorthand <sh>`	Mod shorthand identifier	Auto-generated
`-d, --description <desc>`	Mod description	Empty

Examples:

flint mod create "My Mod" -s mm -d "My custom mod"

flint mod dev

Clone an existing mod for local development.

Usage:

flint mod dev <source>

Examples:

flint mod dev NUU-Cognition/flint-mod-claude-code

flint mod check

Check mod system health.

Usage:

flint mod check

flint mod heal

Fix issues in a specific mod.

Usage:

flint mod heal <name> [--dry-run]

flint mod reinstall

Reinstall a mod's install entries.

Usage:

flint mod reinstall <name> [--force]

flint mod info

Show detailed information about a mod.

Usage:

flint mod info <name>

flint mod add

Add a mod declaration to flint.toml without installing.

Usage:

flint mod add <source>

flint mod remove

Remove a mod declaration from flint.toml only.

Usage:

flint mod remove <name>

flint mod register

Usage:

flint mod register <folder>

flint mod gitinit

Initialize git for a dev mod.

Usage:

flint mod gitinit <name> <url>

flint mod push

Push changes for a dev mod.

Usage:

flint mod push <name> -m <message>

flint mod pull

Pull/sync mod repos.

Usage:

flint mod pull [name]

flint mod scripts

List and run mod scripts.

Usage:

flint mod scripts <name>
flint mod <name> <script-name> [args...]

Helper Commands

flint helper

Utility commands for common workflow operations.

flint helper type newnumber

Get the next available number for a typed artifact.

Usage:

flint helper type newnumber <type> [options]

Arguments:

<type> - Type name (Task, Plan, Notepad, etc.)

Options:

Flag	Description	Default
`-p, --path <dir>`	Path to Flint workspace	Auto-detect
`--raw`	Output raw number without zero-padding	false

Examples:

flint helper type newnumber Task          # Returns "076"
flint helper type newnumber Plan          # Returns "003"
flint helper type newnumber --raw Task    # Returns "76" (no padding)

Git Commands

flint git

Git operations with Flint awareness.

Usage:

flint git [args...] [options]

flint git (no args)

Show git status with Flint context.

flint git init

Initialize git with appropriate .gitignore.

flint git sync

Update .gitignore for current Flint configuration.

Git passthrough

Any other git command is passed through:

flint git status
flint git add .
flint git commit -m "message"
flint git push

Registry Commands

flint register

Usage:

flint register [paths...] [options]

Options:

Flag	Description	Default
`-s, --scan`	Scan directory for Flints to register	false
`-d, --depth <n>`	Max recursion depth for scan	5
`--dry-run`	Preview without registering	false
`-f, --force`	Update existing registry entry	false

Examples:

flint register                          # Register current directory
flint register /path/to/flint           # Register specific path
flint register --scan ~/dev             # Scan and register Flints
flint register --scan ~/dev --dry-run   # Preview what would be found

flint unregister

Remove a Flint from the global registry. Does not delete any files.

Usage:

flint unregister [path] [options]

Options:

Flag	Description	Default
`-f, --force`	Skip confirmation prompt	false

Examples:

flint unregister                        # Unregister current directory
flint unregister /path/to/flint         # Unregister specific path

flint registry validate

Validate and clean the registry.

Usage:

flint registry validate [options]

Options:

Flag	Description	Default
`--dry-run`	Check only, do not remove broken entries	false
`--json`	Output as JSON	false
`-f, --force`	Skip confirmation prompt	false

What it does:

Cleans deprecated fields from old entries
Handles corrupted registry (recreates if needed)
Removes invalid entries (missing name/path)
Finds and removes broken paths

flint registry tag

Add tags to a registered Flint.

Usage:

flint registry tag <flint-name> <tag>

Examples:

flint registry tag "My Project" "important"
flint registry tag "My Project" "active"

flint registry untag

Remove tags from a registered Flint.

Usage:

flint registry untag <flint-name> <tag>

Utility Commands

flint config

View or set global Flint configuration.

Usage:

flint config [action] [key] [value]

Examples:

flint config                            # Show all configuration
flint config get open.apps              # Get specific value
flint config set open.apps '["obsidian", "cursor"]'  # Set value

flint mode

Manage feature mode.

Usage:

flint mode [mode] [options]

Options:

Flag	Description	Default
`-l, --list`	List all features and their availability	false
`-r, --reset`	Reset mode to build default	false

Examples:

flint mode                      # Show current mode
flint mode production           # Set to production mode
flint mode dev                  # Enable all features
flint mode --list               # Show all features by tier

Data Commands

flint export

Manage exports to share content with other Flints.

flint export list

List all exports. Discovers (Export) files in Mesh/.

flint export list

flint export build

Build exports from (Export) documents.

flint export build              # Build all exports
flint export build Guide        # Build specific export
flint export build --all        # Explicitly build all

flint export status

Show export build status.

flint export status

flint import

Manage imports from other Flints' exports.

flint import list

flint import list               # Show all flints with exports
flint import list "NUU Flint"   # Show exports from specific flint

flint import add

flint import add "NUU Flint/Guide"    # Add and pull import

flint import remove

flint import remove "NUU Flint/Guide"                  # Remove from config
flint import remove "NUU Flint/Guide" --delete-files   # Also delete files

flint obsidian

Manage .obsidian/ configuration.

flint obsidian update           # Pull latest from template
flint obsidian reset            # Delete and re-clone
flint obsidian reset --force    # Reset without confirmation

flint workspace

Manage workspace references and repositories. See Module - Workspace for details.

flint workspace list                                    # List references
flint workspace add <name> [--type <type>]              # Add reference
flint workspace reference <name> [path]                 # Add and optionally fulfill
flint workspace fulfill [name] [path]                   # Provide local path
flint workspace remove <name>                           # Remove reference
flint workspace addrepo <name> <url>                    # Clone repository
flint workspace listrepo                                # List repositories
flint workspace updaterepo <name>                       # Re-fetch repository
flint workspace removerepo <name> [--force]             # Remove repository
flint workspace addreferencerepo <name> <url>           # Clone source repository
flint workspace listreferencerepo                       # List source repositories
flint workspace updatereferencerepo <name>              # Re-fetch source repository
flint workspace removereferencerepo <name> [--force]    # Remove source repository

flint connection

Manage connections to other Flints. See Module - Connections for details.

flint connection add <name> [--no-fulfill]              # Add connection
flint connection remove <name>                          # Remove connection
flint connection list                                   # List all connections
flint connection fulfill [name] [--all] [--target <path>] # Provide local paths
flint connection status                                 # Check connection health

flint subflint

Manage nested Flint workspaces. See Module - Subflints for details.

flint subflint create <name> [--preset <preset>] [-d <desc>]  # Create subflint
flint subflint list                                            # List subflints
flint subflint sync                                            # Sync index
flint subflint remove <name> [-y]                              # Remove subflint
flint subflint promote <name> -t <destination>                 # Promote to registered
flint subflint <name> <command...>                             # Run command in subflint

Runtime Commands

Note: Runtime commands require dev mode (flint mode dev).

flint server

Manage the Flint runtime server.

flint server start              # Start server on 127.0.0.1:7433
flint server status             # Check health and active runtimes
flint server stop               # Stop all runtimes and server

flint runtime

Manage individual Flint runtimes. Requires the server to be running.

flint runtime start [path]      # Start runtime for a Flint
flint runtime stop [id-or-path] # Stop a runtime
flint runtime list              # List active runtimes

Global Options

Available on most commands:

Option	Description
`--help`	Show help for command
`--version`	Show CLI version

Reference - Configuration - Configuration file reference
Reference - Hooks Configuration - Hooks configuration reference
Reference - Troubleshooting - Common issues and solutions
Module - Runtime - Runtime system overview
Guide - Quick Start - Getting started with Flint

CLI Reference: Complete Command Guide

On this page