CLI Commands

The Pensum CLI reads your vault directly. No running plugin required.

Output modes

Mode	When	Format
Rich	TTY default	Colored tables, smart column hiding, position numbers
Plain	--plain or NO_COLOR	Tab-separated, header row, grep/awk-friendly
JSON	--json or non-TTY	{ ok, type, data, warnings? } envelope

Resolution: --json / --plain flag → PENSUM_FORMAT env var → NO_COLOR → TTY detection.

Global options

Option	Description
--vault, -v <name|path>	Vault target (named vault or path). Default: current directory or focus.
--json	Force JSON envelope output.
--plain	Force tab-separated text output.

Env vars: PENSUM_CONFIG (config path), PENSUM_VAULT (vault override), PENSUM_FORMAT, NO_COLOR.

Exit codes

Code	Meaning
0	Success
1	User error
2	System error

Multi-vault config

Named vaults live in ~/.config/pensum/config.toml:

default = "personal"

[vaults.personal]
path = "~/vaults/personal"

[vaults.work]
path = "~/vaults/work"

pensum config init           # auto-discover from Obsidian's vault list
pensum config show           # print the resolved config
pensum vaults                # list configured vaults
pensum focus [name]          # show or set the default for writes

With 2+ vaults configured, read commands aggregate by default — results merge into one list with a Vault column and a per-vault footer breakdown. Write commands always target a single vault (focus or --vault=<name>).

Result cache

List commands save their result to ~/.cache/pensum/last-results.json, so subsequent commands can reference rows by position:

pensum task today
#   Description              Pri    Due
1   Renew passport           high   2026-05-20
2   Review Q3 forecast       medium 2026-05-21

pensum task complete '#2'    # completes "Review Q3 forecast"

Cache invalidates whenever you run another list command.

task

pensum task today                                      # due/scheduled today + overdue
pensum task inbox                                      # tasks in Inbox files
pensum task overdue                                    # past due
pensum task week                                       # next 7 days
pensum task list --filter all                          # everything open
pensum task show <ulid|#N>
pensum task add "Fix Caddy config" --due 2026-05-20 --priority high --tags homelab
pensum task complete <ulid|#N>
pensum task edit <ulid|#N> --due 2026-05-21 --priority medium
pensum task delete <ulid|#N> [--dry-run]

project

pensum project list
pensum project dashboard <name>

wiki

pensum wiki list

capture

pensum capture task "Buy milk" --due 2026-05-20
pensum capture stub "K8s networking"

mcp

pensum mcp config                                    # print MCP server config snippet
pensum mcp install --client claude-desktop           # guided install bundle for a client
pensum mcp install --client claude-code
pensum mcp install --client cursor
pensum mcp install --client claude-desktop --read-only
pensum mcp-config                                    # alias for `pensum mcp config`

The install verb prints the exact client config file path, the JSON to merge under mcpServers, restart instructions, and notes on .pensumignore and the audit log. Add --read-only to print a read-only bundle that injects PENSUM_MCP_MODE=read-only into the server’s env block.

utility

pensum schema    # JSON command catalog (always JSON, regardless of mode)
pensum doctor    # vault health check
pensum version