Your vault, from the terminal
taskforge is a command-line to-do app for the tasks and notes in your Obsidian vault. Query and complete tasks, create and edit notes, or hand the same commands to a shell script or an agent. It uses the app's parser and writes real Markdown files on your machine.
CLI or the MCP server?
Use the CLI from shell contexts with no MCP connection: scripts, cron, CI, or a coding agent working in a repo checkout. If your agent already has an MCP connection to TaskForge instead, prefer the MCP tools; they are typed, return structured errors the agent can self-correct against, and need nothing on your PATH. Both drive the same engine with identical semantics, so pick whichever your runtime already has wired up. Editing vault files by hand is the last resort.
Install
Try it with Node.js (includes npm and npx):
Install the taskforge command globally:
Requires Node.js with npm/npx. npm installs a native binary for macOS, Windows (x64) and Linux (x64 and arm64). The TaskForge app has no Linux version yet; on Linux you get the CLI and the MCP server. Install the CLI separately from the app; Homebrew is no longer supported.
Quickstart
Point taskforge at a vault with --vault, or set TASKFORGE_VAULT once. Every read command takes --json for machine-readable output an agent can parse.
Print the vault's task dialect: status symbols, date format, custom fields, where new tasks go. This is what an agent reads first.
Append a task to the vault's default new-task target, formatted the way your vault writes tasks.
Count tasks that carry the custom field priority_label:: urgent, most urgent first. Drop --count to list them.
Find tasks whose description mentions an invoice and whose title mentions acme, as JSON. Accent and case are ignored, so cafe matches café.
Complete a task. If it recurs, the next occurrence is written back into the file, exactly as the app would do it.
Read one task with its content hash, so a follow-up edit can pass --if-hash and refuse to write over a stale copy.
Query grammar
The query argument is a space-separated set of tokens, all of which must match. The common ones:
| text:word | Title contains the word (accent- and case-insensitive). | text:groceries |
| desc:"phrase" | Task description contains the phrase. | desc:"send invoice" |
| tag:name | Task carries the #name tag. | tag:work |
| prop:key=value | Custom field key equals value. | prop:area=home |
| prop:key | Custom field key exists, any value. | prop:estimate |
| --sort due|priority|created | Order the results. Default is due date, soonest first. | --sort priority |
| --count | Return the number of matches instead of the tasks. | --count |
Custom field keys can include letters, digits, and underscores, so priority_label and area_2 both work.
One requirement: the vault contract
taskforge reads a small contract file, TaskForge/Settings/dialect.json, that TaskForge writes into your vault. It describes your exact task format so the CLI edits tasks your way instead of guessing. Open the vault in TaskForge 3.0 or later at least once, go to Settings, AI & Agents, and leave "Generate agent files" on. That writes the contract. TaskForge/Settings is the default location; the base folder can be renamed in the app.
If taskforge cannot find a vault it tells you the three ways to point it at one:
- Pass --vault /path/to/vault on the command.
- Set the TASKFORGE_VAULT environment variable.
- Open the vault once in TaskForge 3.0+ so TaskForge/Settings/dialect.json exists, then run from inside the vault folder.
Local only
taskforge runs on your machine and touches only the markdown files in the vault you point it at. No account, no API key, no network calls. Whatever already syncs your vault, iCloud, Dropbox, or Obsidian Sync, carries the edits to your other devices.
Want an agent to drive it?
The CLI is for terminals and scripts. If you want Claude Desktop or another MCP client to add and complete tasks through a tool interface, set up the MCP server instead. Same vault, same rules. It is the same taskforge binary either way, so taskforge mcp --stdio is all it takes to switch it into an MCP server.
Set up the MCP server →The CLI edits the tasks. The app keeps them alive.
taskforge writes to your vault from any terminal; TaskForge turns those same files into lists, widgets, and reminders on your phone and desktop. Free to download on iPhone, iPad, Mac, Android, and Windows.
