feat(devonthink): add devonthink

[Rowdy]

devonthink

Local-first DEVONthink automation with safer shell workflows than raw AppleScript or MCP alone.

API: devonthink | Category: productivity | Press version: 4.27.0
Spec: https://www.devontechnologies.com/blog/20260526-devonthink-mcp-server

Publication Path

New print

CLI Shape

$ devonthink-pp-cli --help
Devonthink CLI — Local-first DEVONthink automation with safer shell workflows than raw AppleScript or MCP alone.

Highlights (not in the official API docs):
  • context pack   Build a compact evidence packet from records, selections, highlights, links, and related items.
  • privacy audit   Preview what a workflow may expose before content leaves the local machine.
  • batch plan   Stage multi-record edits as validated dry-run plans before applying them.
  • inventory export   Export DEVONthink databases, groups, tags, and document metadata for maintenance plugins.
  • graph audit   Detect orphans, broken links, unresolved wiki links, weak hubs, and tag-only clusters.
  • mirror search   Query a local SQLite mirror for repeatable fast analysis without repeated app calls.
  • mcp call   Call DEVONthink's official local MCP tools from scripts when the local MCP server is enabled.
  • ledger list   Review CLI-driven mutation plans, applies, target proofs, and rollback hints.
  • selection snapshot   Turn the current GUI selection into a reusable JSON workflow seed.
  • agent-context   Emit an agent contract that enforces local-machine and own-LAN DEVONthink access only.

Agent mode: add --agent to any command for JSON output + non-interactive mode.
Health check: run 'devonthink-pp-cli doctor' to verify auth and connectivity.
See README.md or the bundled SKILL.md for recipes.

Usage:
  devonthink-pp-cli [command]

Available Commands:
  agent-context Emit structured JSON describing this CLI for agents
  analytics     Run analytics queries on locally synced data
  api           Browse all API endpoints by interface name
  completion    Generate the autocompletion script for the specified shell
  context       Build a compact local context pack from records, selection, or search
  databases     List open databases
  doctor        Check CLI health
  export        Export data to JSONL or JSON for backup, migration, or analysis
  feedback      Record feedback about this CLI (local by default; upstream opt-in)
  groups        Render a bounded group tree
  help          Help about any command
  import        Import data from JSONL file via API create/upsert calls
  inventory     Export databases, groups, tags, and selected document metadata for downstream tools
  privacy       Preview database scope, content-size budget, and cloud/MCP exposure before handoff
  profile       Named sets of flags saved for reuse
  runtime       Check DEVONthink app, AppleScript, optional MCP, and local mirror readiness
  search        Full-text search across synced data or live API
  sheets        Read a sheet as structured rows
  sync          Sync API data to local SQLite for offline search and analysis
  tags          Analyze tags for duplicates, case drift, action tags, and maintenance tags
  tail          Stream live changes by polling the API at regular intervals
  version       Print version
  which         Find the command that implements a capability
  workflow      Compound workflows that combine multiple API operations

Flags:
      --agent                   Set all agent-friendly defaults (--json --compact --no-input --no-color --yes)
      --allow-partial-failure   Downgrade response-body partial-failure (e.g. partialFailureError) to a warning instead of a non-zero exit
      --compact                 Return only key fields (id, name, status, timestamps) for minimal token usage
      --config string           Config file path
      --csv                     Output as CSV (table and array responses)
      --data-source string      Data source for read commands: auto (live with local fallback), live (API only), local (synced data only) (default "auto")
      --deliver string          Route output to a sink: stdout (default), file:<path>, webhook:<url>
      --dry-run                 Show request without sending
  -h, --help                    help for devonthink-pp-cli
      --human-friendly          Enable colored output and rich formatting
      --idempotent              Treat already-existing create results as a successful no-op
      --json                    Output as JSON
      --max-age duration        Maximum acceptable age of local-store data before a stderr hint suggests sync; 0 disables (default 30m0s)
      --no-cache                Bypass response cache
      --no-color                Disable colored output
      --no-input                Disable all interactive prompts (for CI/agents)
      --plain                   Output as plain tab-separated text
      --profile string          Apply values from a saved profile (see 'devonthink-pp-cli profile list')
      --quiet                   Bare output, one value per line
      --rate-limit float        Max requests per second (0 to disable)
      --select string           Comma-separated fields to include in output (e.g. --select id,name,status)
      --timeout duration        Request timeout (default 1m0s)
  -v, --version                 version for devonthink-pp-cli
      --yes                     Skip confirmation prompts (for agents and scripts)

Use "devonthink-pp-cli [command] --help" for more information about a command.

Novel Commands

Command	Name	Description
records search	Smart Group scoped search	Scope a normal DEVONthink query to a Smart Group by UUID, exact name, or DEVONthink path while preserving normal search output.
context pack	Context pack	Build a compact evidence packet from records, selections, highlights, links, and related items.
privacy audit	Privacy audit	Preview database scope, content-size budget, and cloud/MCP exposure before a handoff.
batch plan	Batch planning ledger	Stage multi-record edits as validated dry-run plans before applying them.
inventory export	Maintenance inventory export	Export DEVONthink databases, groups, tags, and document metadata for maintenance plugins.
graph audit	Knowledge graph audit	Detect orphans, broken links, unresolved wiki links, weak hubs, and tag-only clusters.
mcp call	MCP passthrough	Call DEVONthink's official local MCP tools from scripts when the local MCP server is enabled.

What This CLI Does

This CLI treats DEVONthink as a local knowledge database, not a cloud API. It wraps core record/search operations, adds a SQLite mirror for repeatable analysis, and provides stable inventory, graph, batch, and ledger contracts for higher-level maintenance plugins.

Default operation uses local macOS automation and requires no API key. Optional official MCP passthrough uses DEVONthink's local MCP server when enabled; keep it bound to localhost or the user's own LAN.

Manuscripts

• Local-only Phase 5 Rationale
• Phase 5 Acceptance Marker
• Phase 5 Skip Marker
• Research Brief

Validation Results

Check	Result
Manifest	PASS
Transcendence	PASS
Phase 5	PASS
go mod tidy	PASS
govulncheck (this CLI only, reachable findings)	PASS
go vet	PASS
go build	PASS
--help	PASS
--version	PASS
verify-skill	PASS
Manuscripts	PRESENT

Publish Live Gate

Skipped with explicit reason: lan-unreachable-from-generation-host. DEVONthink is a local macOS app; live calls require the user's local DEVONthink app and local MCP server, not a public internet API.

Gaps

No public cloud API is available for CI-grade live testing. Runtime validation remains local-first through devonthink-pp-cli runtime doctor and the optional official DEVONthink MCP server.

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for da6e9d9790ad2574f1b2ea67152f3a7d2eb71380 after 184s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[greptile-apps]

Greptile Summary

This PR publishes the new devonthink CLI — a local-first DEVONthink automation tool that wraps AppleScript, the optional local MCP server, and a SQLite mirror for offline search. It also includes patches applied in response to a prior round of review (AppleScript list-parsing, mirror-backend disclosure, and isList correctness for search/graph-audit paths).

• Core CLI (~135 files): Go CLI and MCP server binaries, novel commands for Smart Group scoped search, context packs, privacy audit, batch plan/apply, inventory export, and graph audit; all mutations are gated by a local write-block that routes through batch plan first.
• Prior-review fixes: splitOSAList now uses the \\x1e record-separator instead of \", \" (preventing silent corruption of names containing comma-space); localMirrorSync emits \"status\":\"not_implemented\" with explicit warnings; mcp_call.go empty stub removed; isList corrected to true in records_search.go and graph_audit.go.
• Remaining stub: The empty if !stdinBody {} pattern fixed in mcp_call.go was not propagated to 10 other mutation-command files; these are no-ops and do not affect behavior but are dead code left over from code generation.

Confidence Score: 5/5

Safe to merge; the prior-review fixes are well-captured and the remaining empty stubs are no-ops with no runtime impact.

All four issues flagged in the previous review round have been addressed and recorded in .printing-press-patches/devonthink-review-stability-fixes.json. The only new finding is that 10 other mutation command files still carry the same empty if !stdinBody {} block that was fixed in mcp_call.go — these evaluate and immediately fall through without doing anything, so the actual stdin/flag logic beneath them is unaffected. No behavioral regressions or correctness problems were found in the novel commands, the Smart Group scope resolver, the data-source routing, or the AppleScript adapter.

The 10 mutation command files with leftover empty stubs (batch_apply.go, batch_plan.go, ai_ask.go, ai_summarize.go, ingest_file.go, ingest_url.go, media_ocr.go, media_transcribe.go, records_move.go, records_update.go) are worth a quick cleanup pass, but require no fix before merge.

Important Files Changed

Filename	Overview
library/productivity/devonthink/internal/cli/batch_apply.go	Batch apply command with partial-failure detection; empty if !stdinBody {} stub remains (no-op, style issue)
library/productivity/devonthink/internal/client/local_devonthink.go	Previous-review issues resolved: splitOSAList now uses record-separator (\x1e) instead of ", "; localMirrorSync emits "not_implemented" status with explicit warnings
library/productivity/devonthink/internal/cli/mcp_call.go	Empty stdinBody stub removed (addressed from prior review); stdin JSON parsing and POST flow are correct
library/productivity/devonthink/internal/cli/records_search.go	isList now correctly passed as true (fixed from prior review); Smart Group scope resolution wired cleanly
library/productivity/devonthink/internal/cli/graph_audit.go	isList now correctly passed as true (fixed from prior review); offline fallback behavior for graph/audit path corrected
library/productivity/devonthink/internal/client/smart_group_scope.go	New novel command: resolves Smart Group by UUID, exact name, or path via MCP search_records; UUID-ambiguity check and path normalization look correct
library/productivity/devonthink/internal/cli/data_source.go	Data-source routing (auto/live/local), write-through cache, and network-error detection all look well-structured
library/productivity/devonthink/.printing-press.json	Manifest is complete: run_id, printer, printing_press_version, novel_features, and creator all present
library/productivity/devonthink/.printing-press-patches/devonthink-review-stability-fixes.json	Stability-fix patch records the prior-review resolutions but lists only mcp_call.go, leaving 10 other files with the same empty stdinBody stub untracked
library/productivity/devonthink/.printing-press-patches/devonthink-smart-group-search-scope.json	Patch entry correctly records the Smart Group scope feature with validated_outcome and affected file list

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CLI[devonthink-pp-cli command] --> DS{data-source flag}
    DS -->|live| API[Local MCP HTTP 127.0.0.1]
    DS -->|local| Store[SQLite mirror]
    DS -->|auto| LiveTry[Try Live MCP]
    LiveTry -->|success| WriteThrough[Write-through cache to SQLite]
    LiveTry -->|network error| FallbackLocal[Fallback to SQLite]
    LiveTry -->|HTTP 4xx-5xx| Error[Return error]
    API --> OSA[AppleScript fallback]
    OSA --> DTApp[DEVONthink.app local macOS]
    API --> DTApp
    WriteThrough --> Output[JSON / table / CSV]
    FallbackLocal --> Output
    Store --> Output
    subgraph NovelCmds[Novel Commands]
        SG[records search with smart-group]
        CP[context pack]
        BP[batch plan and apply]
        GA[graph audit]
        MCP[mcp call passthrough]
    end
    CLI --> NovelCmds

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    CLI[devonthink-pp-cli command] --> DS{data-source flag}
    DS -->|live| API[Local MCP HTTP 127.0.0.1]
    DS -->|local| Store[SQLite mirror]
    DS -->|auto| LiveTry[Try Live MCP]
    LiveTry -->|success| WriteThrough[Write-through cache to SQLite]
    LiveTry -->|network error| FallbackLocal[Fallback to SQLite]
    LiveTry -->|HTTP 4xx-5xx| Error[Return error]
    API --> OSA[AppleScript fallback]
    OSA --> DTApp[DEVONthink.app local macOS]
    API --> DTApp
    WriteThrough --> Output[JSON / table / CSV]
    FallbackLocal --> Output
    Store --> Output
    subgraph NovelCmds[Novel Commands]
        SG[records search with smart-group]
        CP[context pack]
        BP[batch plan and apply]
        GA[graph audit]
        MCP[mcp call passthrough]
    end
    CLI --> NovelCmds

Loading

_{Reviews (3): Last reviewed commit: "fix(devonthink): correct list fallback r..." | Re-trigger Greptile}

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 2067d37405a964f9bdefcd38d31c06da7289e1ea after 184s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 9f3f8cb715c8bbbba66995c1e5e3cb89412b6e88 after 185s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}