Core command families

Run npm run org2 -- --help for current top-level usage.

Main workflows:

• agenda

• todo

• plan

• capture

• archive, refile

• fmt

• id, query, backlinks

• roam ...

• crypt ...

• export html

• publish

• lint

• lsp

Agenda

Purpose: query scheduled/deadline items across Org files.

npm run org2 -- agenda --dir ~/notes --recursive --from 2026-03-01 --to 2026-03-31

Important behavior:

• Includes both SCHEDULED: and DEADLINE: rows in-range.

• Supports broad filter/sort/group dimensions in CLI + VS Code integration.

• Normalizes common TODO aliases into stable status buckets (including wait/hold/pause-style states).

TODO + planning edits

npm run org2 -- todo toggle --file notes.org2 --line 42 --apply
npm run org2 -- todo set --file notes.org2 --line 42 --status in_progress --apply
npm run org2 -- plan set --file notes.org2 --line 42 --kind scheduled --date 2026-03-25 --apply

Capture / archive / refile

npm run org2 -- capture --file inbox.org2 --title "Quick note" --template note --apply
npm run org2 -- archive --file notes.org2 --pos 120:0 --apply
npm run org2 -- refile --file notes.org2 --pos 120:0 --to-file projects.org2 --to-pos 40:0 --apply

Formatter

Canonical formatting for Org2 files.

npm run org2 -- fmt --dir ~/notes --recursive --check
npm run org2 -- fmt --dir ~/notes --recursive --apply

Corpus lint

Lint is the first compiler-style health pass for artifact metadata and corpus structure.

npm run org2 -- lint --dir ~/notes --recursive

Current checks include:

• invalid or missing ORG2_ARTIFACT_ROLE on generated outputs

• missing/invalid provenance, generator, and generated-at metadata

• duplicate IDs and unresolved provenance references

• conventional corpus-flow checks when you organize notes as raw/ -> notes/ -> compiled/ -> views/ -> publish/

Roam workflows

npm run org2 -- roam db-sync --dir ~/notes --recursive --apply
npm run org2 -- roam node new --dir ~/notes --title "Acme Corp" --apply
npm run org2 -- roam backlinks --id 123e4567-e89b-12d3-a456-426614174000 --dir ~/notes --recursive --format json

Org2 supports both title-based wiki links and explicit id: links, with backlinks across both forms.

Org-crypt

npm run org2 -- crypt decrypt --file secrets.org2 --line 42 --passphrase 'your-passphrase' --apply
npm run org2 -- crypt encrypt --file secrets.org2 --line 42 --passphrase 'your-passphrase' --apply

Export + publish

npm run org2 -- export html --file README.org --out README.html --apply
npm run org2 -- export html --dir docs/site --recursive --out-dir site --apply
npm run org2 -- publish docs-site --config org2.json

Useful export options include TOC, heading numbering, stylesheet injection, and Org-file-link rewrite to HTML targets.

LSP

Start language server:

npm run org2 -- lsp

Current implemented capabilities include:

• definitions/references/hover/completion/signature help

• rename + linked editing for IDs/file links

• file-rename link updates

• formatting (document/range/on-type)

• semantic tokens, inlay hints, code lens, call hierarchy

For full details, see:

• LSP_README.md

• VS Code integration docs