A local-first, AI-native CLI for card-based writing.

mf treats your knowledge base as a codebase. Articles are assembled from composable Blocks, every piece of state lives in plain files on disk, and the CLI is shaped so both humans and Agents can drive it.

Three ideas guide every decision in mf:

Knowledge is meant to spread. Capture it once as a Block, then let it diffuse — through articles, glossary terms, builds, and downstream publishers like Yuque or static sites. The same atomic unit can land in a report today and a paper tomorrow, without copy-paste drift.

flowchart LR
  subgraph Capture
    B((Block))
    S[Source]
    T[Term]
  end
  subgraph Compose
    A1[Article: Report]
    A2[Article: Paper]
  end
  subgraph Ship
    P1[Publisher: Yuque]
    P2[Publisher: Local]
  end
  B --> A1
  B --> A2
  S --> A1
  T --> A2
  A1 --> P1
  A1 --> P2

Your writing follows the same discipline as your infrastructure:

declarative YAML configs (minds.yaml, mind.yaml, mind-index.yaml), schema validation, deterministic builds, and full git auditability. If you can review a PR, you can review a chapter.

mf is designed first for AI Agents, not for human terminal sessions. Every command speaks a JSON envelope ({ status, command, data }), exits with stable codes, and produces deterministic output contracts. Build a pipeline with shell, Make, or an LLM — the contract is the same.

This is an independent philosophy, not a subset of DaC: AI Native CLI rejects interactive prompts, colored output designed for human eyes, and inconsistent exit codes. The tool is a reliable API for an LLM to call.

Local-first underpins all three: no cloud, no lock-in, plain markdown and YAML you can edit in any editor.

Requires Rust 1.75+.

git clone https://github.com/alswl/mind-forge.git
cd mind-forge
cargo install --path .

Or run from source while iterating:

cargo run -- --help

Shell completion:

mf completion zsh   # or bash | fish | powershell | elvish

# 1. Create a Mind Repo
mkdir my-repo && cd my-repo
mf init                                # creates minds.yaml + projects/

# 2. Create a project (path-based identity, Unicode/emoji/dates supported)
mf project new blog
mf project new workspaces/team/projects/2026-W21

# 3. Create an article
mf article new "First Post" --project blog

# 4. Add sources, assets, and terms
mf source new https://example.com/ref --file-kind web --project blog
mf asset new diagram.png --project blog
mf term new "Zettelkasten" --definition "A note-taking method" --project blog

# 5. Index, build, and publish
mf article index --project blog
mf build "First Post" --project blog
mf publish run "First Post" --target local --project blog

See docs/manual.md for the full user manual, including repo layout, shared CLI contracts, scripting patterns, and end-to-end workflows for projects, articles, sources, assets, terms, builds, publishing, templates, and configuration.

All on-disk YAML follows the mind 0.3.0 format (schema: "1"), so repos move freely between mf and other mind-compatible tools.

How the pieces fit on disk:

flowchart TD
  Repo[Mind Repo<br/><code>minds.yaml</code>]
  Repo --> P1[Project: blog<br/><code>mind.yaml</code>]
  Repo --> P2[Project: papers<br/><code>mind.yaml</code>]
  P1 --> Docs[docs/]
  P1 --> Sources[sources/]
  P1 --> Assets[assets/]
  P1 --> Outputs[outputs/]
  P1 --> Idx[<code>mind-index.yaml</code>]
  Docs --> A1[essay.md<br/>file article]
  Docs --> A2[2026-review/<br/>directory article]
  A2 --> A2a[01-intro.md]
  A2 --> A2b[02-details.md]

A typical loop:

flowchart LR
  C[Capture<br/><code>mf source</code><br/><code>mf asset</code><br/><code>mf term</code>]
  D[Draft<br/><code>mf article new</code>]
  I[Index<br/><code>mf … index</code><br/><code>mf project lint --fix</code>]
  B[Build<br/><code>mf build</code>]
  P[Publish<br/><code>mf publish run</code>]
  C --> D --> I --> B --> P
  P -. new insights .-> C

1. Capture — mf source new and mf asset new pull raw material into a project. mf term new records vocabulary.
2. Draft — mf article new <TYPE> <TITLE> [--template <S>] [--file] scaffolds a directory article (default) or single file (--file) under docs/. The default template is blank; --template arch|prd|blog selects another built-in scaffold, and --template <path> reads a project-local Markdown template. New articles automatically get Typora front matter (typora-copy-images-to) pointing to the project assets directory (disable with plugins.typora-front-matter.enabled: false in mind.yaml). Edit in any Markdown editor.
3. Index — mf source index, mf article index, and mf project lint --fix reconcile mind-index.yaml with the filesystem.
4. Build — mf build <article> assembles output (directory articles merge their files in filename order) into outputs/<article>.md.
5. Ship — mf publish run … --target <publisher> pushes to a configured target.

Every step is idempotent and pipe-friendly. Pass --json to any command to get a machine-readable envelope.

These flags are available on most commands:

Shared flag families (uniform across all commands they apply to):

--project is available on project-scoped commands (article, asset, source, term, build, publish run, etc.) and accepts repo-relative paths or project names. When running inside a project directory, --project can be omitted — the CLI auto-detects the current project. When run outside a project directory without --project, mf article list automatically matches all projects and sorts articles by most recently modified.

Bootstrap a directory as a Mind Repo (creates minds.yaml and the default projects/ container). Defaults to the current directory.

Global terms (created without --project) are stored in minds-terms.yaml at the repo root. Project-scoped terms live in each project's mind-index.yaml.

Corrections follow two paths. mf term lint/fix deterministically applies the declared glossary corrections — the closed-set, recurring domain terms — to project docs under guardrails (no edit inside a protected term occurrence, declared-correction precedence, non-overlapping edits, atomic write after diff/confirm). Open-domain ASR errors that no fixed list can enumerate are corrected by the driving agent, then persisted via mf term correction add once they recur. mf owns the deterministic guardrails; the agent owns the open-domain judgment.

-o, --output <PATH>, --dry-run. ARTICLE may be an indexed name/slug or a repo-relative path prefixed with @ (e.g. @projects/blog/docs/2026-03-review/). Directory articles are built by merging Markdown files in filename order. Relative image/link/reference paths are automatically rewritten to resolve from the output directory; paths inside fenced code blocks, absolute paths, and URLs are left unchanged.

Supported shells: bash, zsh, fish, powershell, elvish

Text output includes commit / build_date / rustc. JSON envelope adds target_triple. Pass --json for the machine-readable form.

• Repo bootstrap — mf init [PATH] creates minds.yaml and .mind/
• Project lifecycle — mf project new | list | show | update | rename | remove | archive | lint | index | import; path-based identity supports Unicode, emoji, dates, spaces
• Project auto-detection — running inside a project directory auto-injects --project; mf article list without --project outside a project dir auto-matches all projects, sorted by most recently modified; cwd-relative paths normalized to repo-relative canonical identity
• Article management — mf article new | list | show | update | rename | remove | lint | index; directory articles by default, --file for single-file shape; --template blank|arch|prd|blog or custom project-local template path
• Sources — mf source new | list | show | update | rename | remove | index | clean; --file-kind auto|pdf|file|rss|web, --source-kind yuque|meeting|misc
• Assets — mf asset new | list | show | update | rename | remove | index | clean; --copy/--link for copy vs symlink
• Glossary — mf term new | list | show | update | correction | move | rename | remove | lint; global terms in minds-terms.yaml, project-scoped in mind-index.yaml
• Build — config-driven assembly, directory-article merging, --dry-run, --output, and @path/-style article addressing
• Publish — mf publish run | update | target list | target show against per-target publishers (local, yuque-prompt); project-level local targets resolve relative paths from project root
• Render templates — mf render template list | show covers built-in and project-local templates
• Config — mf config schema | show | generate | default; centralized defaults for docs/, sources/, assets/, _archived/, and outputs/
• Plugins — mind.yaml supports a plugins block for forward-compatible plugin configuration; the typora-front-matter plugin is enabled by default and injects typora-copy-images-to front matter into new articles
• Compatibility — reads and writes mind 0.3.0 YAML; tolerates older schema_version and list-based shapes on read
• Shell completion — mf completion <SHELL> for bash, zsh, fish, powershell, elvish
• Version — mf version includes commit / build_date / rustc / target_triple
• Terminal intelligence — mf config terminal for capability diagnostics; automatic OSC 8 hyperlink rendering in list/show/verb outputs when supported; broad terminal emulator detection (iTerm2, Ghostty, Kitty, VS Code, Warp, Terminal.app, tmux, WezTerm, etc.) plus MF_FORCE_HYPERLINKS/MF_NO_HYPERLINKS overrides; file:// URI encoding for paths with spaces or Unicode
• Output contracts — text by default, --json for { status, command, data } envelopes; canonical per-verb shapes; identity round-trip between list and show; remove/archive use a TTY confirmation protocol; stable exit codes

Every mf command adheres to shared text-layout and JSON-envelope contracts. These are documented in the feature specification:

Key rules:

• data is always a JSON object — no bare arrays, strings, or null
• Text output adapts to TTY (headers + ANSI) vs pipe (no headers, no ANSI, same row shape)
• Every resource carries an identity field that round-trips between list and show
• --dry-run is available on every mutating command
• Remove and archive require confirmation in TTY; non-TTY exits 1 without --yes/--force

See specs/ for detailed specifications and the feature evolution plan.

MIT