Foam CLI (#1636)

Introduces the Foam CLI (`foam-cli` package) — a standalone command-line interface for working with Foam workspaces outside of VS Code.

Commands added:

`foam note` — create, view, and manage notes
`foam rename` — rename a note and update all wikilinks pointing to it
`foam list` — list notes with filtering options
`foam search` — full-text search across the workspace
`foam links` — inspect inbound/outbound links for a note
`foam grep` — regex/glob search across notes
`foam outline` — display the heading outline of a note
`foam lint` — run janitor checks (missing headings, stale definitions) and optionally fix them
`foam tag` — list and filter notes by tag
`foam daily` — create or open daily notes
Also includes full documentation under docs/user/tools/cli/ and test coverage for all commands

Author: riccardoferretti

docs/user/features/daily-notes.md

@@ -60,4 +60,7 @@ To customize your daily note location and format you can create a `.foam/templat
 
 There are also some settings to customize the behavior of daily notes, but they are deprecated and will be removed. Please use the `daily-note.md` template.
 
-[templates]: templates.md "Note Templates"
+To work with daily notes from the terminal, see [[daily|CLI daily command]].
+
+[templates]: templates.md 'Note Templates'
+[daily]: ../tools/cli/daily.md 'foam daily'

docs/user/features/tags.md

@@ -87,4 +87,7 @@ Customize tag appearance in markdown preview by adding CSS:
 
 Some users prefer backlinks (e.g. linking to a `book` note) instead of #book tags for categorization. Both approaches work — choose what fits your workflow.
 
+To manage tags from the terminal, see [[tag|CLI tag command]].
+
 [graph-view]: graph-view.md 'Graph Visualization'
+[tag]: ../tools/cli/tag.md 'foam tag'

docs/user/getting-started/installation.md

@@ -50,6 +50,16 @@ Other extensions:
 - **Paste Image** - Easily insert images from clipboard
 - **Todo Tree** - Track TODO items across your workspace
 
+## Optional: Install the Foam CLI
+
+The Foam CLI lets you work with your workspace from the terminal — search notes, manage tags, create daily notes, and more — without opening VS Code.
+
+```bash
+npm install -g @foam/cli
+```
+
+Once installed, run `foam --help` to see available commands, or see the [[cli|CLI documentation]] for details.
+
 ## What's Next?
 
 Now that Foam is installed, you're ready to:
@@ -75,3 +85,4 @@ If you encounter issues:
 [navigation]: navigation.md 'Navigation in Foam'
 [graph-view]: ../features/graph-view.md 'Graph Visualization'
 [frequently-asked-questions]: ../frequently-asked-questions.md 'Frequently Asked Questions'
+[cli]: ../tools/cli.md 'Foam CLI'

docs/user/tools/cli.md

@@ -1,11 +1,49 @@
-# Command Line Interface
+# Foam CLI
 
-Create a CLI tool to allow running common Foam commands. These may include:
+The `foam` command line tool lets you work with your Foam workspace from the terminal — search, inspect, and manage notes without opening VS Code.
 
-- `foam init` - create a new foam workspace
-- `foam janitor` - run [[workspace-janitor]] in current workspace
-- `foam migrate <tool>` - migrate from tools like roam exports, obsidian and more
+## Installation
 
-More commands to be added.
+```bash
+npm install -g @foam/cli
+```
 
-[workspace-janitor]: workspace-janitor.md 'Janitor'
+## Usage
+
+```
+foam <command> [options]
+```
+
+Set the `FOAM_WORKSPACE` environment variable to avoid typing `--workspace` on every command:
+
+```bash
+export FOAM_WORKSPACE=/path/to/your/notes
+```
+
+All commands accept `--format json` for machine-readable output, useful for scripting.
+
+## Commands
+
+| Command     | Description                                       |
+| ----------- | ------------------------------------------------- |
+| [[daily]]   | Show or create the daily note for a date          |
+| [[grep]]    | Search note content by pattern                    |
+| [[links]]   | Show links to and from a note                     |
+| [[lint]]    | Check notes for issues                            |
+| [[list]]    | List notes, tags, orphans, placeholders, and more |
+| [[note]]    | Show, create, move, or delete notes               |
+| [[outline]] | Show the heading structure of a note              |
+| [[rename]]  | Rename notes, tags, sections, or block anchors    |
+| [[search]]  | Search notes by title, tag, or frontmatter        |
+| [[tag]]     | List, rename, or search tags                      |
+
+[daily]: cli/daily.md 'foam daily'
+[grep]: cli/grep.md 'foam grep'
+[links]: cli/links.md 'foam links'
+[lint]: cli/lint.md 'foam lint'
+[list]: cli/list.md 'foam list'
+[note]: cli/note.md 'foam note'
+[outline]: cli/outline.md 'foam outline'
+[rename]: cli/rename.md 'foam rename'
+[search]: cli/search.md 'foam search'
+[tag]: cli/tag.md 'foam tag'

docs/user/tools/cli/daily.md

@@ -0,0 +1,55 @@
+# foam daily
+
+Show or create the daily note for a date.
+
+```
+foam daily [options]
+```
+
+Without `--create`, the command only reports whether the note exists. With `--create`, it writes the note if it doesn't exist yet, using your daily note template if one is configured.
+
+## Options
+
+| Option                | Description                                                                |
+| --------------------- | -------------------------------------------------------------------------- |
+| `--date <YYYY-MM-DD>` | Date to target (default: today)                                            |
+| `--create`            | Create the note if it doesn't exist                                        |
+| `--path-only`         | Print only the resolved file path (useful for scripting)                   |
+| `--workspace <dir>`   | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) |
+| `--format <fmt>`      | Output format: `text` (default) or `json`                                  |
+
+## Examples
+
+Show today's daily note status:
+
+```bash
+foam daily
+# journals/2024-01-15.md  [exists]
+```
+
+Create today's daily note:
+
+```bash
+foam daily --create
+```
+
+Get the path to a specific date's note (for scripting):
+
+```bash
+foam daily --date 2024-01-10 --path-only
+# /home/user/notes/journals/2024-01-10.md
+```
+
+Open today's note in your editor:
+
+```bash
+$EDITOR $(foam daily --create --path-only)
+```
+
+## Daily note path
+
+If no daily note template is configured, notes are created at `journals/YYYY-MM-DD.md` relative to the workspace root. If a template exists (`.foam/templates/daily-note.md` or `.foam/templates/daily-note.js`), the template determines the file path and content.
+
+See [[templates]] for how to configure daily note templates.
+
+[templates]: ../../features/templates.md 'Note Templates'

docs/user/tools/cli/grep.md

@@ -0,0 +1,49 @@
+# foam grep
+
+Search note content by pattern.
+
+```
+foam grep <pattern> [options]
+```
+
+Searches the text content of all notes in the workspace. The pattern is matched case-insensitively as a regular expression. Unlike [[search|foam search]], this command searches the full text of each note rather than indexed metadata.
+
+## Options
+
+| Option              | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| `--context <n>`     | Show `n` lines of surrounding context around each match                    |
+| `--no-line-number`  | Omit line numbers from output                                              |
+| `--limit <n>`       | Max number of matching files to return (default: 20)                       |
+| `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) |
+| `--format <fmt>`    | Output format: `text` (default) or `json`                                  |
+
+## Examples
+
+Search for a word across all notes:
+
+```bash
+foam grep "quantum"
+# physics/quantum-mechanics.md:3: Quantum mechanics describes...
+# research/reading-list.md:12: See also quantum entanglement
+```
+
+Search with context lines:
+
+```bash
+foam grep "TODO" --context 2
+```
+
+Limit results:
+
+```bash
+foam grep "meeting" --limit 5
+```
+
+Use in a script (JSON output):
+
+```bash
+foam grep "action item" --format json
+```
+
+[search]: search.md 'foam search'

docs/user/tools/cli/links.md

@@ -0,0 +1,62 @@
+# foam links
+
+Show links to and from a note.
+
+```
+foam links (<identifier> | --path <path>) [options]
+```
+
+Displays the outgoing links (notes this note links to) and incoming links (notes that link to this note, also called backlinks). The command can also be invoked as `foam connections`.
+
+## Options
+
+| Option              | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| `--path <path>`     | Target note by exact file path instead of identifier                       |
+| `--outgoing`        | Show only outgoing links                                                   |
+| `--incoming`        | Show only incoming links (backlinks)                                       |
+| `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) |
+| `--format <fmt>`    | Output format: `text` (default) or `json`                                  |
+
+By default, both outgoing and incoming links are shown.
+
+## Examples
+
+Show all links for a note:
+
+```bash
+foam links my-note
+# Outgoing (2):
+#   → related-topic    notes/related-topic.md
+#   → another-note     notes/another-note.md
+#
+# Incoming (1):
+#   ← index            index.md
+```
+
+Show only backlinks:
+
+```bash
+foam links my-note --incoming
+```
+
+Target by file path:
+
+```bash
+foam links --path notes/my-note.md
+```
+
+Get links as JSON for scripting:
+
+```bash
+foam links my-note --format json
+```
+
+## Note identifiers
+
+Foam identifies notes by the shortest unique part of their filename (without extension). For example, a note at `projects/alpha/notes.md` might be identified as `notes` if that's unique, or `alpha/notes` if there's ambiguity. Use [[note|foam note id]] to check how a note is identified.
+
+See also [[backlinking]] for the backlinks panel in VS Code.
+
+[backlinking]: ../../features/backlinking.md 'Backlinks'
+[note]: note.md 'foam note'

docs/user/tools/cli/lint.md

@@ -0,0 +1,75 @@
+# foam lint
+
+Check notes for issues.
+
+```
+foam lint [options]
+```
+
+Scans all notes in the workspace and reports problems such as missing headings or stale link reference definitions. With `--fix`, auto-fixable issues are corrected in place.
+
+Exits with code `2` when issues are found (and no `--fix`), making it easy to use in CI pipelines.
+
+## Options
+
+| Option              | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| `--fix`             | Apply all auto-fixable issues                                              |
+| `--rule <id>`       | Run only the given rule (can be repeated)                                  |
+| `--workspace <dir>` | Workspace root (default: `FOAM_WORKSPACE` env var, then current directory) |
+| `--format <fmt>`    | Output format: `text` (default) or `json`                                  |
+
+## Rules
+
+| Rule ID             | Description                                            | Auto-fixable |
+| ------------------- | ------------------------------------------------------ | :----------: |
+| `missing-heading`   | Notes without a top-level heading                      |     Yes      |
+| `stale-definitions` | Link reference definitions that are outdated or unused |     Yes      |
+
+## Exit codes
+
+| Code | Meaning         |
+| ---- | --------------- |
+| `0`  | No issues found |
+| `1`  | Command error   |
+| `2`  | Issues found    |
+
+## Examples
+
+Check the workspace for issues:
+
+```bash
+foam lint
+# notes/my-note.md
+#   5:1  warning  Missing heading  missing-heading
+#
+# 1 problem (0 errors, 1 warning, 1 fixable with --fix)
+```
+
+Fix all auto-fixable issues:
+
+```bash
+foam lint --fix
+```
+
+Run only one rule:
+
+```bash
+foam lint --rule missing-heading
+```
+
+Use in CI:
+
+```bash
+foam lint || echo "Lint issues found — please fix before merging"
+```
+
+Get results as JSON:
+
+```bash
+foam lint --format json
+```
+
+See also [[workspace-janitor]] for running the janitor from VS Code.
+
+[workspace-janitor]: ../workspace-janitor.md 'Workspace Janitor'