obsidian-cli

obsidian-cli - Obsidian デスクトップの自動化を適切な方法に振り分ける

このスキルは、一般的なノート作成ではなく、ターミナルからの操作や URI による引き継ぎで Obsidian デスクトップを操作する場合に使用します。

obsidian-cli は、公式 CLI の有効化、単発コマンド／TUI の使用、vault=／file=／path= による確実な対象指定、開発者コマンドの実行、公式の obsidian:// による引き継ぎを担当します。また、実際にはヘッドレス同期、ファイルシステムへの直接書き込み、より高度なプラグイン／API による自動化が必要な場合は、適切な別の方法へ正直に振り分けます。

特殊なケースや、依頼の範囲が広がり始めた場合は、次のサポートドキュメントを参照してください。

• references/intake-packets-and-route-outs.md
• references/installation-and-troubleshooting.md
• references/vault-and-file-targeting.md
• references/commands-and-developer-tools.md
• references/uri-and-callbacks.md

このスキルを使用する場合

• ユーザーが公式の Obsidian CLI を有効化または確認したい場合。
• 実行中のデスクトップアプリに対して、obsidian の単発コマンドを実行する、または TUI を使用する場合。
• ワークフローで vault=、file=、path= による明示的な Vault またはノートの指定が必要な場合。
• ユーザーがシェルからデイリーノート、検索、読み取り、作成、タグ、タスク、差分、コマンドパレットのワークフローを実行したい場合。
• ユーザーが Obsidian のプラグイン／テーマを開発しており、plugin:reload、devtools、dev:screenshot、eval、または command id=... が必要な場合。
• 別のアプリ、ランチャー、ショートカット、ブラウザー、またはエージェントのループから、公式の obsidian:// URI による引き継ぎやコールバックの動作が必要な場合。

このスキルを使用しない場合

• 主な作業がデスクトップアプリを使わないヘッドレスの Sync／Publish である場合 → このスキルではなく、Obsidian Headless に振り分けます。
• 主な作業が Vault パス内の一般的な Markdown ファイルの編集である場合 → ファイルシステムへの直接書き込みのほうが簡単で、実態にも即しています。
• 主な作業で、ファーストパーティの CLI／URI では対応できない、より高度な外部 CRUD／フロントマター／ワークスペースの自動化が必要な場合 → 公式 CLI だけで十分だと装わず、Local REST API や Advanced URI などのプラグイン／API を使う方法に切り替えます。
• ユーザーが Obsidian に依存しない、シェルネイティブなノート用バックエンドを求めている場合 → Joplin Terminal、nb、zk などの関連ノート CLI のほうが適しています。

手順

ステップ 1：主な自動化方法を分類する

コマンドを選ぶ前に、依頼の内容を整理します。

obsidian_automation_intake:
  primary_surface: cli-command | cli-tui | cli-developer | uri-handoff | headless-route-out | filesystem-route-out | plugin-api-route-out
  environment: desktop-local | launcher-shortcut | browser-callback | headless-server | unknown
  target_shape: vault-and-note | command-id | uri-action | sync-service | raw-markdown-write
  plugin_dependencies: none | daily-notes | unique-note-creator | plugin-command | unknown

1 回の実行につき、主な方法を 1 つだけ使用します。

• cli-command — 実行中のアプリに対する単発のターミナルコマンド
• cli-tui — 履歴／自動補完を備えた、対話型の obsidian シェル
• cli-developer — プラグイン／テーマ／開発用コマンド、またはコマンドパレットの実行
• uri-handoff — 別のアプリからの obsidian:// による open／new／daily／search／hook コールバック
• headless-route-out — デスクトップアプリを使わない Sync／Publish
• filesystem-route-out — アプリの操作よりも Markdown への直接書き込みのほうが実態に即している場合
• plugin-api-route-out — 要求された自動化に対して、ファーストパーティの CLI／URI では機能が不十分な場合

複数の主な方法を 1 つの回答に混在させないでください。

ステップ 2：CLI を使用する前にデスクトップの実行環境を確認する

references/installation-and-troubleshooting.md を参照してください。

最低限、次の点を確認します。

• デスクトップ版 Obsidian がインストールされている
• Settings -> General -> Command line interface で CLI が有効になっている
• 現在の公式ドキュメントでは、インストーラーのバージョン 1.12.7+ が必要
• マシンから実際にデスクトップへアクセスできる。CI やヘッドレスサーバーで無理に使用しない

ローカルでの簡易確認：

bash scripts/install.sh

デスクトップアプリがない場合、または GUI を使わないタスクが明示されている場合は、直ちに headless-route-out または filesystem-route-out に切り替えてください。

Step 3: 対象を確実に指定する

references/vault-and-file-targeting.mdを使用してください。

ルール：

• デフォルト以外のVaultを対象にする場合は、コマンドの前にvault=<name>またはvault=<id>を指定してください
• ノート名が重複する可能性がある場合は、path=<exact/path.md>を優先してください
• wikilink形式での解決が許容される場合に限り、file=<name>を使用してください
• タスクが明示的に対話型でない限り、アクティブなVault／アクティブなファイルに依存しないでください

例：

obsidian vault="My Vault" search query="meeting notes"
obsidian vault="My Vault" read path="Projects/Roadmap.md"
obsidian vault=Notes command id=editor:focus-top

Step 4: 必要最小限で正確なパケットを選ぶ

references/intake-packets-and-route-outs.mdを使用してください。

デフォルトの選択：

• ターミナル出力が重要な読み取り／検索／作成／タスク／日常作業には、CLIコマンドパケット
• 対話型の探索や履歴には、TUIパケット
• プラグインの再読み込み、スクリーンショット、eval、コマンドパレットの実行には、開発者パケット
• ランチャー、ショートカット、ブラウザーコールバック、アプリへの引き渡しには、URIパケット
• ヘッドレス同期、ファイルへの直接書き込み、プラグイン／APIレベルの自動化には、ルートアウトパケット

Step 5: アプリ自体がランタイムの場合は公式のCLIフローを使う

references/commands-and-developer-tools.mdを使用してください。

最初に実行する安全なコマンド：

obsidian help
obsidian version

よく使われるワンショットフロー：

obsidian daily
obsidian daily:append content="- [ ] Follow up"
obsidian search query="TODO"
obsidian read path="Inbox/Capture.md"
obsidian create name="Trip to Paris" template=Travel
obsidian tags counts
obsidian tasks daily
obsidian diff file=README from=1 to=3

別のツールで結果を使う場合は、--copyを使用してください：

obsidian read path="Inbox/Capture.md" --copy
obsidian search query="launch checklist" --copy

Step 6: 開発者コマンドは別モードとして扱う

開発者コマンドは実際にサポートされているユースケースですが、状態に依存します。

obsidian devtools
obsidian plugin:reload id=my-plugin
obsidian dev:screenshot path=screenshot.png
obsidian eval code="app.vault.getFiles().length"
obsidian commands
obsidian command id=workspace:open-settings

プラグイン／テーマの作業、コマンドの検出、アプリの状態確認には、このモードを使用してください。

Step 7: 引き渡しやコールバックには公式のURIフローを使う

references/uri-and-callbacks.mdを使用してください。

次の公式URIアクションを入口として維持してください：open、new、daily、unique、search、choose-vault、hook-get-address。

例：

obsidian://open?vault=my%20vault&file=my%20note
obsidian://new?vault=my%20vault&name=my%20note
obsidian://daily?vault=my%20vault
obsidian://search?vault=my%20vault&query=Obsidian
obsidian://hook-get-address?x-success=myapp://x-callback-url

ルール：

• 値を正しくパーセントエンコードしてください
• path=はvaultとfileより優先されます
• paneType=windowはデスクトップのみで使用できます
• dailyにはDaily notesプラグインが必要です
• uniqueにはUnique note creatorプラグインが必要です
• コールバックのサポートはエンドポイントごとに異なります。Obsidianの応答後に別のアプリで処理を続ける必要がある場合は、コールバックを優先してください

ヘルパー：

bash scripts/open-uri.sh 'obsidian://open?vault=my%20vault&file=my%20note'

Step 8: 依頼内容が変わった場合は別の手段に切り替える

次のルートアウトを明示してください：

• デスクトップアプリを使わないヘッドレス同期／公開 → Obsidian Headless
• ディスク上のVaultにMarkdownを書き込んで終了 → ファイルシステムへの直接書き込み
• より高度な外部CRUD／frontmatter／ワークスペース制御が必要 → Local REST APIやAdvanced URIなどのプラグイン／APIワークフロー
• Obsidianではなく、シェルネイティブのノートシステムが必要 → Joplin Terminal、nb、またはzk

このスキルを向上させるには、あらゆるノートワークフローに対応できるふりをするのではなく、適さない依頼をすばやく断ることが大切です。

出力形式

簡潔なパケットを1つ使ってください：

• 主要な操作面 — CLIコマンド、TUI、開発者モード、URIによる引き渡し、またはルートアウト
• ランタイムの確認事項 — デスクトップ要件、CLIの有効状態、プラグインの前提条件
• 対象指定 — Vaultとノートの対象。必要に応じて確実性に関する注意事項も記載
• 推奨コマンドまたはURI — タスクに対して必要最小限で正確なコマンド／URI
• 重要な制約 — エンコード、プラグイン依存関係、デスクトップ限定の動作、または状態依存性
• 実際には別の作業である場合 — 明示的なルートアウトとその理由

例

例 1: 公式CLIの登録を確認する

入力：Obsidian CLIを初めて使うのですが、有効化して確認するにはどうすればよいですか？

• bash scripts/install.shを使用する
• Settings -> General -> Command line interfaceに言及する
• 公式のデスクトップCLIの範囲内で回答する

例 2: Vault／パスを確実に指定する

入力：特定のVaultで検索し、特定のノートを読みたいです。fileとpathはどう違いますか？

• vault=はコマンドより前に指定する必要があると説明する
• wikilink形式のfile=と、正確なパスを指定するpath=を比較する
• 曖昧さが問題になる場合は、正確なpath=を優先する

例 3: 開発者向けの作業ループ

入力：開発中のObsidianプラグインをCLIで再読み込みし、スクリーンショットも撮りたいです。

• 開発者モードに切り替える
• plugin:reloadとdev:screenshotに言及する

例 4：URI コールバックワークフロー

入力：外部アプリから obsidian:// リンクでノートを開いたり、新しいノートを作成したりしたいのですが、コールバックも可能ですか？

• 公式の obsidian://open ／ obsidian://new を使用します
• エンコードと x-success ／ x-error について説明します

例 5：デスクトップアプリを使わない同期リクエスト

入力：デスクトップアプリを使わず、CLI だけで同期したいです。

• Obsidian Headless を明示的に案内します
• Obsidian CLI はデスクトップアプリを操作するものであり、この用途には適していないことを伝えます

ベストプラクティス

1. すべてのコマンドファミリーを列挙するのではなく、まず CLI コマンド、URI ハンドオフ、別の手段への案内 のいずれかに分類します。
2. エージェントが安全かつ確定的に対象を指定できるよう、正確な vault= と path= を優先します。
3. 実際の動作がプラグインコマンドによる場合は、commands ／ command id=... を使用します。
4. 別のツールで結果を使用する場合は、--copy または構造化出力形式を使用します。
5. plugin:reload、eval、dev:screenshot、devtools は、特権が必要な開発者向け操作として扱います。
6. URI に関する回答では、エンコード、プラグインの前提条件、デスクトップアプリ限定のコールバック詳細を厳密に扱います。
7. 「Obsidian CLI」という言葉が出てきたというだけで、ヘッドレスサーバーのジョブをこのスキルに回さないでください。
8. OS 固有の登録動作に変更がある場合は、インストール手順を最新の公式ドキュメントで再確認します。

参考資料

• 受付パケットと別の手段への案内
• インストールとトラブルシューティング
• Vault とファイルの指定
• コマンドと開発者ツール
• URI とコールバック
• インストールスクリプト
• コマンド実行スクリプト
• URI を開くスクリプト
• Obsidian CLI
• Obsidian URI
• Obsidian Headless