devonctl

devonctl is an unofficial command-line interface for DEVONthink designed for both people and AI agents.

It uses DEVONthink's native macOS scripting interface through osascript, then adds terminal ergonomics:

• human-readable output by default
• --json output for agents
• commands, schema, manifest, and docs discovery
• focused first-class commands for common DEVONthink workflows
• call and batch for structured automation plans
• dry-run output and confirmation gates for writes

Install

cd /Users/abdo/Developer/devonctl
./install.sh --bootstrap --agent all

Use ./install.sh --help to see bootstrap options. Without --bootstrap, the installer only links devonctl into ~/.local/bin.

Or run without installing:

PYTHONPATH=src python3 -m devonctl --help

Examples

devonctl doctor
devonctl onboard
devonctl commands
devonctl commands --json
devonctl schema search --json
devonctl manifest --json
devonctl docs --command search
devonctl docs --output DEVONthink-commands.md
devonctl install-skill --agent codex --dry-run
devonctl install-skill --agent all --force
devonctl batch '[{"command":"status","arguments":{}}]' --json
devonctl databases
devonctl selected
devonctl current
devonctl children GROUP_UUID --limit 20
devonctl tree GROUP_UUID --max-depth 3
devonctl database-tags --database-uuid DB_UUID
devonctl tags RECORD_UUID
devonctl lookup --url https://example.com
devonctl duplicates RECORD_UUID
devonctl links RECORD_UUID --direction both
devonctl media RECORD_UUID --json
devonctl metadata RECORD_UUID
devonctl reminder RECORD_UUID
devonctl search "kind:pdf tags:invoice" --limit 10
devonctl read UUID --max-tokens 4000
devonctl text UUID
devonctl similar --uuid UUID --limit 10
devonctl classify UUID
devonctl create "Project note" --type markdown --content "# Notes" --dry-run
devonctl rename UUID "New Name" --dry-run
devonctl move UUID --destination "Records/Projects" --dry-run
devonctl trash UUID --dry-run
devonctl import ~/Downloads/report.pdf --destination "Records/Financial" --dry-run
devonctl call search --params '{"query":"kind:markdown","limit":5}' --json

Discovery

devonctl commands
devonctl schema search --json
devonctl manifest --json
devonctl docs

commands lists the human-facing command surface. schema returns static command metadata. manifest is the agent-oriented contract, including backend command names for call and batch.

Batch Plans

batch validates JSON plans as a dry run by default:

devonctl batch @plan.json --json
devonctl batch @plan.json --execute --json
devonctl batch @destructive-plan.json --execute --yes --json

Plan shape:

{
  "operations": [
    {
      "command": "search",
      "arguments": {
        "query": "kind:pdf",
        "limit": 5
      }
    }
  ]
}

Use --execute only after reviewing the dry-run output. If a batch plan contains destructive or full-replacement calls, execution also requires --yes.

Agent Skill

Install the bundled agent skill after installing the CLI:

devonctl install-skill --agent codex
devonctl install-skill --agent claude --dry-run
devonctl install-skill --agent openclaw --dry-run
devonctl install-skill --agent all --force

The command honours CODEX_HOME, CLAUDE_HOME, and OPENCLAW_HOME, refuses to overwrite changed skill files unless --force is passed, and supports --json.

First-Class Workflows

Navigation:

devonctl databases
devonctl selected
devonctl current
devonctl children GROUP_UUID --limit 50
devonctl tree GROUP_UUID --max-depth 4 --documents
devonctl parents RECORD_UUID
devonctl database-tags --database-uuid DB_UUID

Records:

devonctl lookup --name "Project note"
devonctl lookup --url https://example.com
devonctl duplicates RECORD_UUID
devonctl links RECORD_UUID --direction outgoing --kind both
devonctl properties RECORD_UUID
devonctl metadata RECORD_UUID
devonctl tags RECORD_UUID
devonctl reminder RECORD_UUID
devonctl text RECORD_UUID
devonctl read RECORD_UUID --query "invoice,total,due date" --max-tokens 4000

Writes:

devonctl create "Meeting Notes" --type markdown --content "# Notes" --destination "Projects"
devonctl rename RECORD_UUID "Better Name"
devonctl move RECORD_UUID --destination "Archive/2026"
devonctl content RECORD_UUID --mode append --text "Follow-up notes"
devonctl metadata-set RECORD_UUID --arg doi=10.1234/example --dry-run
devonctl reminder-set RECORD_UUID --due-date 2026-06-01T14:00:00Z --schedule once --dry-run
devonctl reminder-clear RECORD_UUID --dry-run
devonctl reminder-clear RECORD_UUID --yes
devonctl export RECORD_UUID --path ~/Desktop/DEVONthink-Export
devonctl import ~/Downloads/report.pdf --destination "Records/Financial" --dry-run
devonctl mkdir "Records/Projects/2026" --dry-run
devonctl capture https://example.com --type markdown --dry-run
devonctl ocr RECORD_UUID --dry-run
devonctl trash RECORD_UUID --dry-run
devonctl trash RECORD_UUID --yes

Use --dry-run on write commands to see the exact backend command and arguments without changing DEVONthink. trash, reminder-clear, and full replacement calls require --yes unless --dry-run is used.

metadata-set defaults to merge mode for first-class CLI use. Pass --mode replace only when you intend to replace the record's full custom metadata object.

devonctl refuses local filesystem reads and writes inside .dtBase2, .dtSparse, and .dtArchive packages. That guard applies to @file inputs, generated docs output, and filesystem paths passed to import/export tools.

DEVONthink intelligence:

devonctl classify RECORD_UUID
devonctl similar --uuid RECORD_UUID --limit 10
devonctl similar --content "research excerpt or project notes" --limit 10 --json

Completion

devonctl completion zsh > ~/.zfunc/_devonctl
devonctl completion bash

Onboarding and Health Checks

devonctl onboard
devonctl doctor --json

doctor verifies DEVONthink, osascript, devonctl on PATH, uv, native automation, and installed agent skill freshness. onboard combines that health report with quick-start commands, completion setup, and the bundled agent skill path.

Agent Contract

Agents should prefer:

devonctl --json commands
devonctl --json schema search
devonctl --json manifest
devonctl docs --json
devonctl install-skill --agent all --json
devonctl --json doctor
devonctl create "Note" --type markdown --content "# Notes" --dry-run --json
devonctl batch @plan.json --json
devonctl --json call search --params '{"query":"kind:pdf","limit":5}'

Use first-class commands for common workflows, and use call for backend automation commands that do not need a dedicated shortcut. Before creating records from URLs, names, or filesystem references, run devonctl lookup --json to avoid duplicates.

Never edit files inside .dtBase2, .dtSparse, or .dtArchive packages directly. Use devonctl or DEVONthink itself for record operations.