Registry Management

How to manage the Flint registry for tracking and discovering workspaces.

Overview

The Flint registry is a local database that tracks all your flint workspaces. It follows a git-like local-first model — your flints are identified by their filesystem path, not by UUIDs. Cloud features (when available) will add remote tracking, similar to git remote.

Local Registry (~/.flint/registry.json)
─────────────────────────────────────────
{
  "version": 1,
  "flints": [
    {
      "name": "My Project",
      "path": "/path/to/flint",
      "type": "flint",
      "tags": ["active"],
      "description": "Main workspace"
    }
  ]
}

Registry Structure

Each registry entry contains:

Field	Description
`name`	Human-readable name from `flint.toml`
`path`	Absolute filesystem path (primary identifier)
`type`	The flint type (typically `flint`)
`tags`	Optional array of tags for categorization
`description`	Optional brief description

Note: The path uniquely identifies each flint, just like a git repository is identified by its directory. Tags and description are synced from flint.toml and can also be managed via flint registry tag.

Commands

flint registry validate

Validate and clean the registry:

# Validate and auto-fix issues
flint registry validate

# Check only, don't make changes
flint registry validate --dry-run

# Skip confirmation prompt
flint registry validate --force

# Output as JSON
flint registry validate --json

What it does:

Cleans registry structure — Removes deprecated fields (id, created) from old entries
Handles corruption — Recreates registry if JSON is invalid
Removes invalid entries — Entries missing required name or path
Finds broken paths — Entries pointing to non-existent directories
Auto-fixes — Removes broken entries (unless --dry-run)

Example output:

Registry Validation

Registry: ~/.flint/registry.json (23 entries)

  ✓ Cleaned 5 entries (removed deprecated fields)

Found 2 issues:

Broken paths (2):
  ✗ Old Project: ~/projects/deleted-project
  ✗ Test Flint: ~/temp/test

Remove 2 broken entries? (y/N) y

  ✓ Removed Old Project
  ✓ Removed Test Flint

Cleaned 2 broken entries

flint list

View all registered flints:

# List all flints
flint list

# Show path validity status
flint list --status

# Output as JSON
flint list --json

flint register

Add a flint to the registry:

# Register current directory
flint register

# Register specific path
flint register /path/to/flint

# Scan and register multiple flints
flint register --scan ~/projects

# Force re-register (update existing entry)
flint register --force

flint unregister

Remove a flint from the registry:

# Unregister current directory
flint unregister

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

# Skip confirmation
flint unregister --force

Note: This only removes from the registry. The flint files remain on disk.

Common Scenarios

After Cloning a Flint

git clone <repo> "(Flint) my-project"
cd "(Flint) my-project"
flint register
flint sync

After Moving a Flint

# The old path becomes broken
flint registry validate
# Removes the broken entry

# Register at new location
cd /new/path/to/flint
flint register

Cleaning Up Old Entries

# See what's broken
flint registry validate --dry-run

# Fix everything
flint registry validate --force

Finding Unregistered Flints

# Scan a directory tree
flint register --scan ~/dev

# Preview what would be registered
flint register --scan ~/dev --dry-run

Registry File Location

The registry is stored at ~/.flint/registry.json. This is a global file shared across all terminals and applications.

~/.flint/
├── registry.json      # Flint registry
├── config.toml        # Global configuration
└── presets/           # Custom presets

Automatic Registration

Flints are automatically registered when:

Created with flint init
Registered manually with flint register
Synced with flint sync (updates name/path if changed)

Flints are automatically unregistered when:

Removed with flint unregister
Cleaned by flint registry validate (broken paths only)

Tagging Flints

You can add tags to registered flints for organization:

# Add a tag
flint registry tag "My Project" "important"

# Remove a tag
flint registry untag "My Project" "old-tag"

Tags are also synced from the tags field in flint.toml during flint sync.

Migration from Old Registry

If your registry has old-format entries (with id, created, or other deprecated fields), running flint registry validate will automatically clean them:

$ flint registry validate

Registry Validation

Registry: ~/.flint/registry.json (15 entries)

  ✓ Cleaned 15 entries (removed deprecated fields)

✓ Registry is valid - no issues found

This migration happens automatically and preserves all your flint entries.

Troubleshooting

"Flint not found in registry"

The flint isn't registered. Either:

# Register it
flint register /path/to/flint

# Or scan for unregistered flints
flint register --scan ~/projects

Duplicate entries after moving

If you moved a flint without unregistering:

# Clean up broken entries
flint registry validate

Registry appears corrupted

# Validate will fix corruption
flint registry validate

If the JSON is unparseable, it will create a fresh empty registry.

Flint shows as "broken" but exists

The path in the registry doesn't match the actual location. Either:

The flint was moved — register at the new location
The path has special characters — check for encoding issues

Guide - Creating a Flint — Creating and initializing flints
Reference - CLI Commands — Full command reference
Guide - Global Configuration — Global settings

On this page