cli-anything-joplin

cli-anything-joplin

このスキルを使用すると、実際の joplin ターミナルバイナリをバックエンドとするステートフルなハーネスを通じて、Joplin のノートブック、ノート、ToDo、タグ、添付ファイル、検索、同期、インポート/エクスポートのワークフローを自動化できます。

要件

• Python 3.10+
• joplin として利用可能な Joplin ターミナルバイナリ
• オプション: 特定の Joplin プロファイルを対象にするには --profile を渡します

インストール

cd joplin/agent-harness
pip install -e .

使用方法

# REPL mode (default)
cli-anything-joplin

# Machine-readable one-shot command
cli-anything-joplin --json notebooks list

# Stateful project
cli-anything-joplin project new --name demo -o ./demo.joplin-harness.json
cli-anything-joplin --project ./demo.joplin-harness.json notes create "Meeting note"

# Dry-run (no auto-save)
cli-anything-joplin --json --dry-run --project ./demo.joplin-harness.json notes create temp

JSON 出力の契約

--json が有効な場合、コマンドは以下を返します:

• ok: boolean
• command: notes.list、todos.toggle のような安定したコマンド識別子
• data: コマンドのペイロード
• error: 成功時は null、失敗時は { type, message }

コマンドグループ

• project: new、open、save、info、json、status
• notebooks: list、create、use、remove
• notes: list、create、set、get、remove、copy、move、rename
• todos: list、create、toggle、clear、done、undone
• tags: list、add、remove、notetags、tagnotes
• search: run
• sync: run (--target、--upgrade、--use-lock)
• interop: import、export
• config: get、set、list、export、import-file
• attach: add
• status: show、restore
• backend: version、dump、keymap、geoloc、export-sync-status
• server: status、start、stop
• e2ee: status、target-status、decrypt、decrypt-file
• session: status、undo、redo、history

エージェント向けのガイダンス

• 解析可能な出力には --json を優先してください。
• 複数ステップのワークフローを実行する場合は --project を使用して、履歴が保持されるようにしてください。
• 単発の変更コマンドは、--dry-run が設定されていない限り、プロジェクトを自動保存します。
• REPL モードでは自動保存されません。明示的に project save を実行してください。
• 一部の Joplin CLI ビルドでは search が GUI モードで制限されます。 "only available in GUI mode" が表示された場合は、検索をベストエフォートとして扱ってください。
• Joplin 3.6.x では、npm グローバルレイアウトにおいて version コマンドが壊れていることがあります。ハーネスは backend version のためにインストール済みパッケージのメタデータにフォールバックし、シンボリックリンクを解決したバイナリディレクトリ、Windows 形式の兄弟パス node_modules/joplin、Unix 形式の親パス lib/node_modules/joplin、そして最後に npm root -g を順に探索します。
• コマンド結果のバックエンド stdout/stderr はそのままです。警告がノート本文やエクスポートから除去されたと想定しないでください。
• 失敗時は、成功時と同じ command フィールドを使用して error を解析してください (config.import_file、e2ee.decrypt_file)。複数単語のサブコマンドでは、グループとサブコマンドの間に単一のドットを使用します。

テストワークフロー

# Quick feedback loop
python -m pytest -q cli_anything/joplin/tests/test_core.py
python -m pytest -q cli_anything/joplin/tests/test_full_e2e.py::TestCLISubprocess

# Real backend (joplin must be in PATH)
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendCommands
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendWorkflows
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendIntegration

# Full suite
python -m pytest -v --tb=no cli_anything/joplin/tests

# Verify the installed console script entry point
CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/test_full_e2e.py

現在の検証ベースライン (Windows + Joplin CLI 3.6.2):

• python -m pytest -q cli_anything/joplin/tests/test_core.py -> 107 passed
• python -m pytest -q cli_anything/joplin/tests -> 134 passed, 1 skipped