Skip to main content

Your vault, from the terminal

taskforge is a small command-line tool that reads and writes the tasks in your Obsidian vault. It uses the same parser the app does, so recurring tasks advance, archives land in the right place, and your task lines stay in your format. Hand it to a shell script or an agent and it edits real markdown files, nothing hosted.

Coming in TaskForge 3.0

The TaskForge CLI and MCP server ship with the TaskForge 3.0 release. Everything on this page describes how they will work at launch. The TaskForge app is available today.

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

macOS and Linux, through Homebrew:

Available at launch 
brew install azhard/tap/taskforge

Prefer npm? The same binary ships as a package:

Available at launch 
npm install -g taskforge

An app-bundled copy that installs itself when you open a vault is coming. Until then, the tap above is the way in.

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.

taskforge schema

Print the vault's task dialect: status symbols, date format, custom fields, where new tasks go. This is what an agent reads first.

taskforge add "call the plumber" --due 2026-07-10 --priority high

Append a task to the vault's default new-task target, formatted the way your vault writes tasks.

taskforge query 'prop:priority_label=urgent' --sort priority --count

Count tasks that carry the custom field priority_label:: urgent, most urgent first. Drop --count to list them.

taskforge query 'desc:"invoice" text:acme' --json

Find tasks whose description mentions an invoice and whose title mentions acme, as JSON. Accent and case are ignored, so cafe matches café.

taskforge done <task-id>

Complete a task. If it recurs, the next occurrence is written back into the file, exactly as the app would do it.

taskforge show <task-id> --json

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/schema.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.

If taskforge cannot find a vault it tells you the three ways to point it at one:

  1. Pass --vault /path/to/vault on the command.
  2. Set the TASKFORGE_VAULT environment variable.
  3. Open the vault once in TaskForge 3.0+ so taskforge/schema.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, and Android.

Apple Get Free - iOS & Mac Android Get Free - Android