CLI

CLI

The track command is the source of truth for the vault. Every subcommand that changes note content reindexes immediately, so search and links stay current without a separate build step. Commands that return data print single-line JSON.

Rebuild the index safely

track reindex --full rebuilds the disposable search and link index from note files and their sidecar metadata. It resets the SQLite schema in place, so a running native or web workspace does not lose its database connections. If a read fails during the rebuild, wait for the command to finish and use Retry in the workspace.

The cache filename includes its schema version. After an update, Track builds a fresh compatible cache automatically; older cache files are left alone so an older CLI cannot replace the database used by a newer workspace. This does not copy or rename vault notes. Use matching up-to-date native and CLI versions, and restart the workspace after updating.

Do not delete the vault's .track/ directory: its sidecars and history are authoritative, not a disposable cache. If manually removing old cache files, first stop all Track processes that could be using them. See Recovering from a note load error.

Stop the web workspace

track web stop --addr 127.0.0.1:8765 stops the managed server at that address and prints {"stopped":true}. An already stopped server or a missing PID record prints {"stopped":false}. Use the same machine configuration and cache location as the server. The command does not restart it automatically. In Neovim, :Track webStop uses the same CLI operation; see Start, stop, and update the server for restarting after an update, address selection, and missing PID records.

Preview an external Markdown file

Start track web, then run track markdown -- "./docs/README.md". It prints JSON containing a one-use viewer URL. Open it in a browser within one minute. From Neovim, :Track markdown opens the saved current file and starts or reuses the workspace automatically. Neither command imports a vault note. See Markdown viewer for the containing-folder scope, limits and refresh behavior.

Creating and editing notes

For standalone calendar records, use track event list, track event get, and track event save. See Calendar events for JSON examples, revision checks, retries, dates, and restoring trash. Event files remain separate from note indexing.

--body is read from piped stdin when the flag is omitted:

printf '本文 [[他ノート]]\n' | track open --title "メモ"

Anything that prints Markdown can therefore create notes — the Web clipper uses this to turn a web page into a note in one pipeline:

track-fetch-web --note https://example.com/essay | track new --title "An essay"

Preserving source evidence

Save a fixed version of an existing note before using it as evidence:

track source save --id 100 --source 'https://example.org/article' \
  --format text/html --at '2026-09-19T10:30:00+09:00'
track source list --id 100
track cite --id 100 --version SAVED_VERSION --heading 'Results'

source save returns a record with a version hash and its owning note_id. Identical source location, media type, body and original bytes reuse the saved version even across note IDs (created:false). Use the returned ID and version for citations and inputs. Duplicate working notes are kept unchanged; source list for them may be empty. Changed content creates another version. --original /path/to/file.pdf also preserves the exact original file. --at records retrieval time, not an inferred publication time. The working note remains editable; saved versions survive reindexing and generation pruning. Back up .track/sources with the vault. Versions are not automatically deleted.

Preserve a summary or extraction separately, naming the exact input version:

track source save --id 200 --input 100:SAVED_VERSION \
  --method 'summarizer/model-v1' --settings 'prompt-v1' \
  --format text/markdown --at '2026-09-19T10:35:00+09:00'

An identical input and recipe across notes reuses the saved result. Changed settings produce a separate version. Use --run regeneration-1 for an explicit regeneration, reusing that key for retries. Deleted owners or corrupt saved records return errors instead of silently choosing another note. These commands freeze existing notes; they do not fetch documents or generate summaries.

cite returns exact text, note ID, version, content hash and resolved line range as JSON. Select an exact --heading (optionally --level 2), --block proof, both --start-line 10 --end-line 15, or --page 2. Lines and physical pages are 1-based. Pages require form-feed boundaries already captured in the text; printed page numbers are not interpreted. No selector returns the full body. Without --version, the result reads the current body and reports pinned:false.

Renaming a note does not break its ID-based citation. Missing or deleted notes, missing versions and invalid or ambiguous positions produce errors. Citation IDs are local to a vault; moving a note to another vault does not move its saved versions. Only the explicitly supplied original file is copied; other attachments and remote links are not recursively preserved.

Capture, refile, archive

These three commands move text around by heading anchor. A target is written as Note#Heading, the same grammar as a [[Note#Heading]] link; add more # to pin a heading level (Note##Sub). They are safety-first: an anchor that matches more than one heading is refused rather than guessed, and a move writes and verifies the destination before it touches the source, so a failed write never loses text.

Capture appends to a heading of a target note, creating the note when it is the configured inbox and does not exist yet. With --template, the captured text fills the template's {{ title }} placeholder, so a one-line note becomes a framed entry. Set the default inbox with capture_inbox in the vault config (<vault>/.track/config.yml; it defaults to Inbox).

# with a template like:  - [ ] {{ title }}
track capture --target "Projects#Inbox" --template task --body "ship the release"

Given this note:

## Inbox

## Done

the capture packs a task under Inbox:

## Inbox
- [ ] ship the release

## Done

Refile moves a whole heading subtree (nested headings travel with it) from one anchor to another. The --line N variant moves a single list item at line N of the source note instead, carrying its nested items. Text moves verbatim, so [[links]] inside it keep resolving; both notes are reindexed so backlinks follow the move.

track refile --from "Notes#Draft" --to "Archive 2026#Kept"   # a subtree
track refile --from "Notes" --line 4 --to "Notes#Done"       # one list item

Archive moves a subtree into a dedicated archive note — per year by default (archive_note: "Archive {{year}}" in the vault config <vault>/.track/config.yml) — and records where it came from, so provenance survives the move:

## Done

*Archived from [[Projects]] on 2026-07-11.*

- [ ] review the draft

Archiving is a living move, distinct from track rm, which soft-deletes a whole note into the trash.

Formatting notes

track fmt rewrites notes into a canonical Markdown style. It is the style counterpart to track doctor: doctor reports breakage, fmt fixes style. The rule set is small and idempotent - running it twice changes nothing the second time.

The rules are: strip trailing whitespace, collapse runs of blank lines (except before headings) and drop blank lines at the start and end, put two blank lines before and one after each heading, normalize unordered-list bullets to -, and end the file with a single newline. Fenced code blocks are never touched, so their contents stay exactly as written.

Closed ATX headings are stripped of their trailing hashes - ## Title ## becomes ## Title - and track fmt --all additionally reorders each metadata sidecar's YAML keys into canonical order.

A note like this:

# Notes
first line
* apple
+ pear



## Details
done

becomes:

# Notes

first line
- apple
- pear


## Details

done

Code stays verbatim - the bullets and blank lines inside a fence are left alone:

```text
*  this bullet is code, not a list


so these blank lines survive
```

Finding notes

Curating tags

track notes --untagged is the pull side of a tagging pass: it returns exactly the notes that still need tags, so a person — or an automated helper — can work through them one at a time. Add tags to an existing note with track append, which merges them into the sidecar without touching the body:

track notes --untagged                       # {"notes":[{"note_id":…,"title":"Draft","tags":null}, …]}
track append --title "Draft" --tag zettel    # merge a tag; the note drops off the untagged list

Journals are date-titled and have their own Web workspace surfaces, so they never appear in the note listing.

Tasks, assets, templates, and Babel

Task lines are edited through the same engine path used by the web board. track task set assigns a state, track task cycle advances through the fixed state order, and track task date writes a scheduled or due date. track tasks lists indexed tasks with state and deadline filters. See Tasks for the notation and board.

track asset import <file> copies an attachment into the vault's assets/ directory and returns the reference to embed; track asset dir --ensure creates that directory when needed. The template commands manage reusable note templates: track template new --name <s>, track template open --name <s>, and track template list.

Babel source blocks are available through track babel exec or track babel run (execute a block), track babel tangle (write :tangle blocks to files), and track babel restore (list stored results). These commands return JSON and keep block results in the note sidecar.

Named vaults

When the machine config has a vaults: registry, track vault list shows the registered vaults and marks the active one, track vault current reports the active name, path, and selection source, and track vault which <name> resolves a name to its path. Pass --vault <name> to any command to run it against a registered vault; the vault registry is machine configuration, not part of a synced vault.

Generation history

Generation history is a local, note-tree snapshot mechanism. track gen increment [--label <s>] saves the working vault, track gen undo and track gen redo move through the linear history, track gen list reports the cursor and whether the working tree is dirty, and track gen status lists the files behind that dirty state. Use track gen peek [--gen N] with a note selector to read an older note without moving the cursor. A vault with gen: false keeps no generations, so all of these commands refuse to run.

Moving a note between vaults

track mv (--id N | --title S | --path P) --to <vault> moves a note to another registered vault, preserving its id and sidecar and updating backlinks. It refuses to leave local links unresolved by default. Use --unlink to turn links that would break into plain text, or --qualify to rewrite them as links qualified with the source vault's name.

Maintenance

track refresh-all runs the whole maintenance pipeline in one idempotent pass: a full reindex followed by a read-only doctor health report. It changes no notes, so it is safe to run unattended on a schedule (cron or launchd) to keep the index in step with a vault that a cloud sync edits behind track's back.

track refresh-all
# {"reindex":{"indexed":42,"deleted":0,"links":17},"doctor":{"scanned":42,"issues":[],"ok":true},"took_ms":12}

A crontab line that refreshes every 15 minutes:

*/15 * * * * /usr/local/bin/track refresh-all >/dev/null 2>&1

Publishing

track export writes a single note out as Markdown. track export-site builds a whole static HTML site — see Web workspace for the rendered reading experience it mirrors.

Static apps under apps/<name>/ are separate from note selection and are not published by default. Pass repeatable or comma-separated --app names to allowlist them. --apps-base-url changes where the published links point when apps are hosted separately; it does not upload them. See Static apps for the complete workflow.

track export-site --all --out ./site

--all publishes every note in the vault (this help site is built that way); --id publishes a selection instead. The landing page comes from the vault config's web.home, and each page's icon, tags, and parent from its sidecar — see Home dashboard. --base-url, --out, and --frontend describe one build of the site rather than the site, so they stay flags.

track render turns a declarative View Spec into a chart or article — see Visualization.

track render --spec chart.json --out chart.svg --renderer svg

Internal command

track dump is reserved for internal placeholder state: today it prints only the version and an empty entries array. It is not a vault export or a supported way to inspect note data.