Command line

mtm reads and changes your Actions and Matters straight from the notes, for scripts, scheduled jobs and the terminal. Obsidian doesn’t need to be running.

mtm works with the Actions and Matters in a vault from a terminal or a script. It reads and writes the notes themselves, applying the same rules as the plugin, so Obsidian doesn’t need to be running; if it is, it picks the changes up like any other edit.

It works only with the data of Matters that Matter: Actions, Matters and the workflow. It never deletes anything and never changes settings, and every write says what it changed, property by property.

Install

mtm needs Node.js 20 or later. Run it without installing anything:

npx -y matters-that-matter today --vault ~/Notes

Or install it once, and type mtm:

npm install -g matters-that-matter
mtm today --vault ~/Notes

The examples below use mtm; with npx, write npx -y matters-that-matter in its place.

Your vault

Name the vault with --vault, or set MTM_VAULT once:

export MTM_VAULT=~/Notes
mtm today

The vault needs Matters that Matter installed and set up in Obsidian, since mtm reads the plugin’s settings for your statuses, types and folders. Before setup, reads work and say so; writes are refused. If your vault’s configuration folder isn’t .obsidian, name it with --config-dir.

Commands

$ mtm --help
Matters that Matter, from the command line.            matters-that-matter 0.1.0

  mtm today                    What matters today?
  mtm add <text> [fields]      Add an Action (quick add’s words work)
  mtm update <action> [fields] Change an Action
  mtm done <action>            Mark as done
  mtm reopen <action>          Reopen a done Action
  mtm show <action>            Everything about one Action
  mtm list [filters]           Actions, done hidden
  mtm add-matter <name>        New Matter
  mtm matters                  Matters in board order
  mtm workflow                 Statuses, types and Spheres
  mtm parse <text>             What quick add would make of it
  mtm open <action|matter>     Open it in Obsidian
  mtm mcp                      Run as an MCP server (stdio)

  --vault <path>   the vault (or MTM_VAULT)      --json      for scripts
  --dry-run        show what would change       --help      this

mtm <command> --help shows each command’s fields and filters. mtm mcp runs the MCP server for AI assistants.

Naming things. An Action is named by its path (MTM/Actions/Call Marco about the quote.md, .md optional) or its title. Matters and people are named by name, path or link text, loosely, as quick add matches them; statuses, types and Spheres by label or ID. When a name matches several Actions, nothing is written and mtm lists them:

$ mtm done "Call Marco"
Several Actions match “Call Marco”:
  MTM/Actions/Call Marco about the quote.md
  MTM/Actions/Call Marco back.md
Use the path, or more of the title.

The examples on this page come from the sample content, on Friday 9 October 2026, and from a small vault with a kitchen renovation and a builder called Marco Rossi.

What matters today?

$ mtm today
What matters today?  Friday 9 October · ~/Notes

Due today or late
  ● Buy      Pay the council tax                     Household admin            Yesterday    high
  ● Call     Confirm the worktop measurements        Kitchen renovation         Today 10:00  high
  ● Message  Answer Eve's question about the essay   Research methods course    Yesterday    medium
  ● Message  Reply to the new enquiry                Advisory practice          Today        medium
  ● Message  Data export from Bob                    Lakeside strategy review   Tue 6 Oct
  ● Visit    Visit the tile showroom                 Kitchen renovation         Wed 7 Oct

4 to sort in the Inbox · 3 reviews due · 2 long waits

As on the Today page: what’s due today or late, or, when nothing is, the next Actions (“Nothing due today. Next up:”); then the Inbox, the reviews due and the long waits.

Add an Action

$ mtm add "Call Marco about the quote /call #Kitchen fri 10:00 !1"
Added “Call Marco about the quote”
  Kitchen renovation · Later · Call · due Fri 16 Oct 10:00 · high priority
  MTM/Actions/Call Marco about the quote.md

The text works as in quick add: /type, #Matter, @person, !1 to !3, and dates in words, in the languages turned on in the plugin’s settings. Fields given as options win over the text. A name that matches nothing falls back as quick add does (the default type, the Inbox, the backlog status), and the output says so in a line:

$ mtm add "Ask about the gym /message #Gym"
Added “Ask about the gym”
  Inbox · Later · Message
  No Matter matches “Gym”, so it went to the Inbox.
  MTM/Actions/Ask about the gym.md

Nothing else is created: no Matters, no people. A new Action never takes a name another note in the vault already has: it gets ” 2”, so links to that note keep reaching it.

Fields

add and update take the same fields:

Option	Value
`--title <text>`	The title. On `update`, it renames the note
`--matter <name>`	A Matter
`--status <status>`	A status
`--type <type>`	An Action type
`--priority <p>`	`1`, `2` or `3`, or `high`, `medium` or `low`
`--start <date>`, `--due <date>`	`2026-10-16`, `2026-10-16T10:00`, or words such as `"fri 10:00"`
`--waiting-on <name>`	A person (a note); they are added to the people too
`--people <name>`	A person; repeat for more. On `update`, the list replaces the people
`--details <text>`	The details
`--checklist <item>`	A checklist item; repeat for more. On `update`, they are added
`--link <note or address>`	A note in the vault or an `http(s)` address, added as a line at the end

$ mtm add "Order the sink" --matter Kitchen --type buy --due 2026-10-20 --waiting-on Marco --checklist "Pick a size"
Added “Order the sink”
  Kitchen renovation · Later · Buy · due Tue 20 Oct · waiting on Marco Rossi
  MTM/Actions/Order the sink.md

Change an Action

update changes only the fields you give. Remove a value with --no-priority, --no-start, --no-due, --no-waiting-on or --no-people:

$ mtm update "Confirm the worktop measurements" --status doing --no-priority --checklist "Check the corners"
Changed “Confirm the worktop measurements”
  mtm-status    next → doing
  mtm-priority  1 → (none)
  checklist     + Check the corners
  MTM/Actions/Confirm the worktop measurements.md

update is strict: a value that matches nothing is refused, with the values that would work, and nothing is written. Moving an existing Action somewhere by accident would be worse than asking again.

$ mtm update "Call Marco about the quote" --status Someday
No status matches “Someday”. Statuses here: Later, Next, Doing, Waiting, Done.
Nothing was changed.

Renames and links

A new title renames the note. When Obsidian’s Automatically update internal links is on in that vault, mtm updates the links to it in other notes, as Obsidian would, keeping their aliases and headings, and lists every note it touched:

$ mtm update "Call Marco about the quote" --title "Call Marco about the revised quote"
Renamed to “Call Marco about the revised quote”
  MTM/Actions/Call Marco about the revised quote.md
  Updated 3 links in 2 notes:
    Daily/2026-10-08.md        lines 3, 12
    Notes/Kitchen plan.md      line 7

When another note already has the new title and links are being updated, links to that other note are rewritten with its path, so they keep reaching it, as Obsidian does. When the setting is off, links are left as they are, as Obsidian would leave them, and mtm says how many now point to the old name. A new title that another note already has is then refused, since links to that note could lead to the Action instead. Try it with --dry-run first to see which notes would change.

Mark as done and reopen

done sets your done status and today’s completion date; reopen moves a done Action back to the backlog status and removes it:

$ mtm done "Send the invoice"
Marked as done “Send the invoice”
  mtm-status     doing → done
  mtm-completed  (none) → 2026-10-09
  MTM/Actions/Send the invoice.md

$ mtm reopen "Order the tiles"
Reopened “Order the tiles”
  mtm-status     done → later
  mtm-completed  2026-10-01 → (none)
  MTM/Actions/Order the tiles.md

Asking again changes nothing: ““Send the invoice” is already as asked. Nothing was changed.”

Show and list

show gives everything about one Action: its values, details, checklist, people and the names of the notes it links to.

$ mtm show "Confirm the worktop measurements"
Confirm the worktop measurements
  Kitchen renovation · Next · Call · due today 10:00 · high priority
  MTM/Actions/Confirm the worktop measurements.md

  Confirm the worktop measurements before ordering.

  Checklist (1 of 2)
    [ ] Ask for the revised quote
    [x] Measure the wall

  Linked notes: Some note, Marco Rossi

list shows open Actions grouped by Matter, in board order. Values the plugin doesn’t recognise are named, as the badges on the board name them:

$ mtm list
Inbox
  ● Call     Call Marco back                    Later
  ● Write    Mystery                            Later                             Not recognised: status “someday” (shown as Later), type “fax” (shown as Write), Matter “[[Nowhere]]” (shown in the Inbox)
  ● Buy      Pay the council tax                Next     Yesterday, late

Kitchen renovation
  ● Call     Confirm the worktop measurements   Next     Today 10:00, late  high
  ● Call     Call Marco about the quote         Next
  ● Message  Revised quote from Marco           Waiting                           waiting on Marco Rossi, 2 weeks

Advisory work
  ● Write    Send the invoice                   Doing    Tue 20 Oct

7 Actions

Filters combine: --matter, --status, --type, --sphere, --person (with them, or waiting on them), --due-from <date>, --due-to <date>, --waiting, and --done to include done Actions. A done status in --status shows done Actions.

$ mtm list --waiting
Kitchen renovation
  ● Message  Revised quote from Marco   Waiting  waiting on Marco Rossi, 2 weeks

1 Action

Matters and the workflow

$ mtm matters
Inbox                      4 open
Kitchen renovation         Home · 7 open · 2 today or late · 1 waiting · reviewed 3 days ago
Household admin            Home · 4 open · 1 today or late · 1 waiting · review due
Learn to sail              Home · dormant · 1 open
Lakeside strategy review   Advisory · 5 open · 1 today or late · 1 waiting · reviewed yesterday
…

add-matter adds a Matter, last on the board, with --icon (a Lucide name, such as house), --sphere, --state (active, dormant or closed), --outcome and --review-every (7d, 2w, 1m):

$ mtm add-matter "Garden shed" --sphere Home --review-every 2w --outcome "A dry place for the tools"
Added Matter “Garden shed”
  Home · active · review every 2 weeks
  A dry place for the tools
  MTM/Matters/Garden shed.md

workflow lists the statuses, types and Spheres with the IDs notes store:

$ mtm workflow
Statuses
  Later    later    Open    backlog
  Next     next     Open
  Doing    doing    Active
  Waiting  waiting  Active
  Done     done     Closed  done

Action types
  ● Call     call
  ● Message  message
  ● Write    write    default
  ● Meet     meet
  ● Buy      buy
  ● Visit    visit

Spheres
  Home      home
  Advisory  advisory
  Research  research
  Teaching  teaching

Try quick add’s words

parse shows what quick add would make of a text, and writes nothing:

$ mtm parse "Call Marco about the tiles /call #Kitchen @Marco @Zed fri 10:00 !1"
“Call Marco about the tiles”
  Kitchen renovation · Later · Call · due Fri 16 Oct 10:00 · high priority
  People: Marco Rossi
  Read: /call, #Kitchen, @Marco, @Zed (matched nothing), fri 10:00, !1
  No note matches “Zed”, so it is left out.

Open in Obsidian

mtm open opens an Action’s note or a Matter’s overview in Obsidian, through an obsidian://mtm-open link:

$ mtm open "Send the invoice"
Opening “Send the invoice” in Obsidian.
  obsidian://mtm-open?vault=Notes&file=MTM%2FActions%2FSend%20the%20invoice.md

The link names the vault by its ID from Obsidian’s own list of vaults, so two vaults whose folders share a name can’t be confused; when the list doesn’t know the folder, by the folder’s name. If the system can’t open the link, mtm prints it for you to open. Opening links on Windows hasn’t been tried yet.

Dry runs

--dry-run shows what a write would change, and writes nothing:

$ mtm done "Call Marco about the quote" --dry-run
Would change MTM/Actions/Call Marco about the quote.md
  mtm-status     next → done
  mtm-completed  (none) → 2026-10-09
Nothing written (dry run).

Output for scripts

--json prints JSON. Reads give both the raw properties and the values the plugin shows, so a script never has to work out the rules itself. The first Kitchen Action in Next, at 9:00 on 9 October (shortened: the full result also has the start date, who it’s waiting on and since when, the completion date and more):

mtm list --matter Kitchen --status next --json | jq '.[0]'

{
  "path": "MTM/Actions/Confirm the worktop measurements.md",
  "title": "Confirm the worktop measurements",
  "matter": { "path": "MTM/Matters/Kitchen renovation.md", "name": "Kitchen renovation", "isInbox": false },
  "status": { "id": "next", "label": "Next", "category": "open" },
  "type": { "id": "call", "label": "Call" },
  "priority": 1,
  "due": "2026-10-09T10:00",
  "today": true,
  "overdue": false,
  "orphans": [],
  "raw": { "mtm-kind": "action", "mtm-status": "next", "…": "…" }
}

Writes give the Action (or Matter) after the write, whether anything changed, dryRun, written, every change (changes), warnings, the links a rename updated (links) and danglingLinks, how many links are left pointing to the old name.

Errors are JSON too, on standard output: { "error": { "code", "message", … } }, with candidates when a name matches several things. Other warnings, such as settings from a newer version of Matters that Matter, go to standard error, so standard output stays the answer.

Colour is used only when the output is a terminal and NO_COLOR isn’t set, and nothing is said by colour alone.

Exit codes

Code	Meaning
0	Done
1	Nothing matched, several things did, a value can’t be read, the command or its options aren’t right, or a note’s properties aren’t valid YAML or use YAML the command line can’t change safely (anchors, aliases, tags; change those in Obsidian). Nothing was written. Also when `mtm open` couldn’t open the link
2	The vault isn’t ready: no vault named or no settings of Matters that Matter (nothing runs), or, for a write, setup not done or settings from a newer version of the plugin (reads still work then, and say so; writes are refused)
3	The vault changed while `mtm` was writing (a note changed, appeared or went away, twice in a row), a write would have gone outside the vault, a note to be changed is read-only, or writing failed and everything was put back. If the vault changed, try again; make a read-only note writable first. In the rare case that something couldn’t be put back, the message names those files

Safety

Only the plugin’s lines. Only mtm- properties change, and in an Action’s body only its details, checklist and links. Everything else in a note stays as it is, line endings included. The one change to other notes is a rename’s link updates, described above.
All or nothing. Every note is checked against what was read before anything is written. New contents go to hidden temporary files beside the notes, then move into place; if a step fails, everything already moved is put back. If another program changed a note in the meantime, mtm reads again once, then gives up (exit code 3) rather than overwrite that change.
Inside the vault. Nothing is written outside the vault folder, nor through a link (symlink) to a folder elsewhere. Linked files and folders are skipped when reading.
Read-only notes stay as they are. A note made read-only (say with chmod 444) is never written: the whole write is refused (exit code 3) and nothing changes.
Nothing deleted, and settings never written.
Obsidian open at the same time is fine. It sees each change as it lands, and since the completion and waiting-since dates are already set, Matters that Matter doesn’t set them again.