CLI Reference

This page reflects the current top-level command surface in apps/flint-cli/src/index.ts. It is organized as a reader-facing map of the CLI rather than a raw dump of every flag.

How to Read the CLI

Flint's commands fall into a few broad jobs:

create and register workspaces
declare and sync the environment
manage external dependencies and active repos
run or coordinate agents
publish workspace knowledge
automate the workspace

If you are new to Flint, the most important starting commands are still:

flint init
flint sync
flint shard list
flint whoami

Workspace Lifecycle

`flint init`

Create a new Flint workspace.

Important options:

--preset <name>
--from-git <url>
--path <dir>

`flint list`

List registered Flints from the local registry.

Important flags:

--json
--full-path
--status
--group
--tag <tag>
--search <query>

Reconcile the current workspace against flint.toml. This is the command that makes a declared Flint environment locally usable by installing shards, reconciling sources, checking references, and aligning supporting files.

`flint repair`

Repair common structural issues in the current workspace.

`flint migrate`

Run pending workspace migrations. Supports --dry-run.

`flint delete`

Delete a registered Flint and its directory. Treat this as destructive.

`flint update`

Check for or install the latest @nuucognition/flint-cli.

Registry and Identity

`flint register`

`flint unregister`

Remove a Flint from the registry without deleting its files.

`flint registry`

Inspect and work with the registry directly.

`flint iam`

Set the current person identity for the active Flint.

`flint whoami`

Show the current workspace identity.

Environment Modules

`flint shard`

Manage the shard layer, which is the main way a Flint gains cognitive programs.

Common subcommands:

install, uninstall, list, update, pull
check, heal, info
create, dev, edit, freeze
add, remove, reinstall
pin, unpin, versions
publish, unpublish, published, release
git, gitinit, push, register
scripts

`flint source`

Manage external source material copied into the workspace.

Subcommand groups:

repo
meshexport

repo supports:

add
remove
update
list

meshexport supports:

add
remove
list

`flint workspace`

Manage active repositories inside Workspace/Repos/.

Subcommands:

create
remove
update
list

`flint reference`

Manage named references to external codebases and other Flints.

Subcommands:

codebase
flint
remove
list

`flint fulfill`

Fulfill a declared codebase reference with a local path.

Current supported resource type:

codebase

`flint resolve`

Resolve a fulfilled resource to its local path.

Current supported types:

codebase
flint
source

`flint export`

Manage buildable Mesh exports.

Subcommands:

list
scan
add
remove
build

`flint send`

Send a bundle of files to another registered Flint's inbox.

Agents and Coding Tools

`flint code`

Launch interactive coding agents in the current Flint.

Subcommands:

claude
codex
gemini

These commands integrate the coding tool with Flint's session export and workspace context model.

`flint agent`

Manage headless agent sessions.

Subcommands:

claude — launch a headless Claude Code session
list — list all sessions
watch — stream live session transcript
session — inspect or manage a specific session
interface — agent I/O interface

session supports actions:

title
register
status
kill
respond
return
artifact

interface supports:

set
get
ask — blocks and waits for response
request — posts deferred question and exits

`flint export-session`

Export a Claude Code session transcript from the current Flint.

`flint export-codex-session`

Export a Codex session transcript from the current Flint.

`flint lattice`

Manage lattice connections and execute lattice functions.

Subcommands:

list
run
connect
disconnect
pin
unpin
sync

`flint server`

Manage the local Flint server.

Subcommands:

start
status
stop

`flint runtime`

Manage runtimes through the local server.

Subcommands:

start
stop
list

This command group is dev-gated in the current CLI.

Utilities

`flint git`

Git passthrough plus Flint-specific helpers.

Special subcommands:

init
sync
publish

If the first argument is not one of those helpers, Flint passes the rest through to git.

`flint tinderbox`

Orchestrate operations across multiple Flints in a Tinderbox.

Subcommands:

sync — materialize, register, and wire the declared Tinderbox
git-backed declarations are owned/materialized; registry:Name declarations are references
git sync — run git sync across all child Flints
whoami <name> — set identity across all child Flints
status — show present/registered/connection state per declared Flint
check — detect drift between tinderbox.toml and reality
heal — auto-fix drift and re-run reconciliation

All flint tinderbox subcommands use walk-up discovery to find tinderbox.toml, so they can be run from the Tinderbox root or from inside a child Flint.

update
reset

`flint config`

Manage global Flint configuration.

Subcommands:

open
get
set

`flint helper`

Small workflow helpers. The most common current one is:

flint helper type newnumber <Type>

`flint features`

List and manage feature flags through the shared CLI-core feature system.

Authentication helpers supplied through the shared CLI core.

Practical Advice

For everyday work, think in terms of a few dependable loops:

init to create the environment
sync to materialize declared capabilities and dependencies
agent or code to run the work
export to publish results

That sequence matches Flint's actual shape as a workspace where agents execute cognitive programs and leave durable artifacts behind.

On this page