Jovie

@jovie/cli

AI エージェント向けの Jovie です。1 つのパッケージで CLI、MCP サーバー、エージェントスキルを提供します。 エージェントは、対応するソーシャル URL から公開クリエイターデータを抽出したり、Spotify の音楽アーティストに Jovie プロフィールを作成して、アーティストに申請リンクを渡したりできます。 ログインも API キーも必要ありません。

インストール

Node.js 24.21 以降が必要です（24 と 26 でテスト済みです。Node 22.13 以降でも実行できますが、プロキシには対応していません）。npm から正確なバージョンの公開リリースをグローバルにインストールします。

npm install --global @jovie/[email protected]
jovie --help
jovie --version

または、インストールせずに実行します：npx -y @jovie/[email protected] --help。

自動インストールの前に、npm view @jovie/cli version を使用してレジストリで利用可能か確認してください。リポジトリのビルドが成功しても、npm にパッケージがある証明にはなりません。

コマンド

コマンド	リクエスト
music resolve <input>	/api/music/mcp の読み取り専用 resolve ツール。アーティスト名／URL／MBID、トラックの URL／ISRC、アルバムの URL／UPC、アーティスト名／タイトルでの検索に対応します
creator lookup <url-or-handle>	GET /api/agents/creator-lookup。抽出には YouTube チャンネル URL または youtube:handle を使用します。既存の Jovie プロフィールの検索には、YouTube、Instagram、TikTok、Linktree の URL または platform:handle を使用します。ソースの制限については以下を参照してください。
profile create <url>	Spotify アーティスト URL を指定して POST /api/agents/profiles を実行します
artist get <username>	GET /api/v1/{username}
artist llms <username>	GET /{username}/llms.txt
api openapi	GET /api/v1/openapi.json
docs llms	GET /llms.txt（/llms-full.txt には --full を指定します）
report bug|feedback --title <text> --details <text>	POST /api/agents/feedback を実行し、reportId を返します
mcp	上記のコマンドを MCP ツールとして stdio 経由で提供します
init	インストール済みの各エージェント（Claude、Codex、OpenClaw、Hermes）に jovie/SKILL.md をインストールします
skill	スキルを表示します

profile create は、該当する Spotify アーティストをすでに保持するプロフィールがある場合、そのプロフィールを変更せずに返します。ない場合は、未申請のプロフィールを作成します。レスポンスには profileUrl と、未申請の場合は claimUrl が含まれます。申請 URL は所有権を示すトークンではありません。アーティスト本人が Spotify アーティストの所有者であることを引き続き確認する必要があります。プロフィールは匿名で作成され、IP ごとにレート制限が適用されます。

music resolve は、プロバイダーリンクとその出所、曖昧な場合の候補を返します。また、正確な URL リレーションまたは MBID によってアーティストを特定できる場合は、MusicBrainz の基本的なアーティスト情報も返します。名前の一致だけでは、プロバイダー間で同一人物であることは確認できません。ソーシャルリンクとメタデータリンクは、リスニングリンクとは別に扱われます。埋め込みのリリースグループ情報は不完全な場合があります。その範囲は releaseGroupsComplete で示されます。

jovie music resolve https://open.spotify.com/artist/4Uwpa6zW3zzCSQvooQNksm --json
jovie music resolve 51972833-bb04-46b7-9401-45a5ab449ebd --json
jovie music resolve USABC1234567 --kind track --territory GB --json
jovie music resolve "Take Me Over" --kind track --artist "Tim White" --json
jovie music resolve 123456789012 --kind album --json

creator lookup は読み取り専用で、Jovie プロフィールを作成または変更することはありません。そのチャンネルをすでに保持する公開 Jovie プロフィールがある場合（ユーザー名の推測ではなく、チャンネル ID で照合します）、レスポンスは {"exists":true,"username":...,"profileUrl":...} となり、ソースページは取得されません。抽出に対応しているのは YouTube チャンネルのみです。一致するプロフィールがない YouTube チャンネルの場合は、表示名、自己紹介、アバター URL、公開リンクとともに {"exists":false,...} を返します。一致するプロフィールがない Instagram、TikTok、Linktree の入力は SOURCE_UNSUPPORTED（HTTP 422、終了コード 1）を返します。Jovie はこれらのページをサーバーから読み取らないためです。代わりに、クリエイターの YouTube チャンネル URL を使用してください。Bandcamp とカスタムウェブサイトは UNSUPPORTED_URL（HTTP 422、終了コード 1）を返します。これらはこのコマンドの対応ソース外です。YouTube の結果に Linktree リンクが含まれていても、その Linktree ページの抽出に対応していることを意味しません。

--json は API のレスポンスを JSON 形式で出力し、テキストリソースは {"content":"..."} でラップします。失敗時は {"error":{...}} を出力し、API の失敗にはサーバーの安定した apiCode（たとえば RATE_LIMITED や ARTIST_NOT_FOUND）が含まれます。成功したコマンドは終了コード 0、リクエスト／レスポンスの失敗は終了コード 1、無効な使用方法は終了コード 2 で終了します。

--help --json は { "content": "..." } を返し、--version --json は { "version": "..." } を返します。 読み取りでは、一時的な障害（接続リセット、エラーコードを伴わない502、503、504、およびRetry-Afterが5秒以下の429）の場合、バックオフを挟んで最大3回試行します。Retry-Afterがそれより長い場合は、待機せずにその値を報告します。書き込みは自動的に再試行しません。タイムアウトは、サーバーで処理が確定した後に発生した可能性があるためです。そのため、レポートツールは冪等性を示しません。すべての試行、バックオフ、本文の読み取りは、1つの30秒の期限を共有するため、コマンドがそれ以上待つことはありません。期限を変更するには、JOVIE_TIMEOUT_MS（1000～120000）を設定してください。本文のサイズ上限は1 MiBです。

エラーは、次に行うべきことを示す1行のメッセージとしてstderrに出力されます（例：Could not resolve jov.ie. Check your internet connection or --base-url.）。スタックと原因の連鎖も出力するには、--debugを追加してください。どちらの場合も、シークレットはマスキングされます。 出力パイプが早期に閉じられた場合（jovie docs llms | head）、静かに終了します。

すべてのコマンドで、互換性のあるデプロイ先のオリジンを指定する--base-url <url>を使用できます。 値はhttpまたはhttpsのオリジンである必要があり、パス、認証情報、クエリパラメーターを含めることはできません。

プロキシ

スタンドアロンCLIとMCPサーバーは、Node.js 24以降ではNode組み込みのプロキシサポートを通じて、HTTP_PROXY、HTTPS_PROXY、NO_PROXY（および小文字の同等の環境変数）を使用します（Node 22では警告が表示され、直接接続します）。追加のNodeフラグは不要です。既存のTLS証明書設定は引き続き有効です。 プロキシはデプロイ先ホスト（通常はjov.ie）への接続を許可する必要があります。CLIをインストールしても、ネットワークアクセスが付与されるわけではありません。

JavaScriptクライアントをインポートしても、ホストアプリケーションのグローバルなトランスポート設定は変更されません。そのアプリケーションでNodeのプロキシサポートを設定するか、クライアントオプションでfetchImplを渡してください。

MCP

{ "mcpServers": { "jovie": { "command": "npx", "args": ["-y", "@jovie/cli", "mcp"] } } }

ツール：lookup_creator、create_profile、get_artist、get_artist_guide、get_openapi、 get_docs、report_issue、report_feedback。server.jsonには、MCPレジストリ向けのパッケージ情報が記述されています。

リポジトリのエージェント

リポジトリのルートにある.mcp.jsonは、node packages/jovie-cli/dist/cli.js mcpを使って、stdio経由でjovieを登録します。リポジトリのルートからMCPクライアントを起動する前に、ワークスペースCLIをビルドしてください。また、CLIを変更した後も再ビルドしてください。

pnpm --filter @jovie/cli build

ローカルエージェントは、タスクをカバーするツールがある場合、エージェント用ルートへの場当たり的なcurl呼び出しよりも、このjovie MCPサーバーを優先してください。現在のチェックアウトから、公開されている製品機能を利用します。このエントリにはログインもAPIキーも不要で、JOVIE_WORKER_TOKENを消去するため、引き継がれたワーカーの認証情報によって内部ツールが公開されることはありません。 製品のMCPの使用は任意であり、リポジトリのエージェント要件ではありません。

JavaScriptクライアント

import { createProfile, fetchArtist, lookupCreator } from '@jovie/cli';

const creator = await lookupCreator('https://www.youtube.com/@creator');
// or by handle: await lookupCreator('youtube:@creator');
const profile = await createProfile('https://open.spotify.com/artist/<id>');
const artist = await fetchArtist('artist-username');

境界

公開コマンドは認証情報を送信せず、何もキャッシュせず、jovie-cli/<version>のUser-Agent以外のテレメトリーを送信しません。書き込みを行うのはprofile createとreportのみです。レポートに含まれるのは、CLIのバージョン、プラットフォーム、ランタイム、および渡したフィールドのみです。initが書き込むのは、既存のエージェントスキルディレクトリ内、または--dirで指定した場所のjovie/SKILL.mdのみです。コマンドではNode 24の組み込み機能（parseArgs、fetch、readline）を使用し、ランタイム依存関係はありません。内部フリートコマンドには、以下に記載する別個のスコープ付き認証情報境界があります。MCPサーバーが対応するのはツールのみです。リソース、プロンプト、またはHTTPトランスポートが必要な場合は、公式SDKを採用してください。

リポジトリにはすでにNode 24のnode:util.parseArgs、組み込みのfetch、AbortSignal.timeout、TypeScript、Vitest、Biomeが用意されています。内部フリートコマンドでは、RESTおよびMCPトランスポートと同じ正規のActionsコントラクトを使用します。

Commander/CAC（MITライセンス、ランタイム依存関係なし）、yargs（MITライセンスですが、より大規模）、oclif（拡張性はありますが、要件に対して過剰）、PythonのClick/Typer、またはHomebrew（2つ目のランタイム／配布経路が必要）を検討しました。どれも、この固定コマンドのTypeScript専用機能群には、ネイティブな基盤ほど適していません。

決定：公開製品コマンドとスコープ付き内部フリートコマンドには、依存関係のないNode 24 CLIを1つだけ使用し続けます。Ovieは、同じシステムのオペレーター向けビューとして引き続き利用します。

内部フリートチャネル

これらのコマンドを使用するには、デプロイ済みのフリートトランスポート、オペレーターによる有効化、個別にプロビジョニングされたワーカー ID が必要です。このパッケージをインストールしても、エージェントは登録されず、会社へのアクセス権も付与されません。公開プロダクトセッションでは、フリート操作を承認できません。

コマンド	目的
fleet register	プロビジョニングされた権限の範囲内で、機能と稼働状況を通知します
fleet status	このワーカーの現在のリース、リクエスト、完了時のレシートを読み取ります
fleet directory	ワーカーの可視性スコープで許可された、証明済みのピアを検出します
work request	範囲を限定したヘルプ、社内テスト、または調査作業を提案します。実行権限は付与されません
work next	条件に合う、承認済みのオファーを受け取ります
work claim	オファーの期限が切れる前に獲得します
work report	完了結果と証拠を永続化します
defect report	正規の Linear アダプターを介して、証拠のある不具合の重複を排除します

すべてのコマンドで、--profile <provisioned-profile-uuid>、 --idempotency-key <stable-invocation-key>、および --input '<canonical-json>' が必要です。 新しい呼び出しごとに新しいキーを使用してください。同じ呼び出しを復旧する場合に限り、キーとペイロードを完全に同じにして再利用してください。登録キーを再度使用すると、元の登録が再生されます。稼働状況の更新にはなりません。

fleet status は、直近のデータの制限付きビューと、永続化された完了履歴を返します。最初のページでは --input に {"historyAfter":0,"historyLimit":50} を指定してください。次のページでは history.nextCursor を使用し、ページごとに新しい呼び出しキーを指定してください。結果がさらに届いたときに再開できるよう、最後のエントリーの sequence を保存してください。各ページは、リクエストされた項目数の上限（1～100）とレスポンスのバイト予算の両方を守ります。history.pending は、以前のホットレコードに制限付きのアーカイブ処理がまだ必要であることを意味します。別のステータス呼び出しで処理が続行されます。移行中も、すべての結果は永続化されます。現在のリクエスト一覧が大きい場合は、requestsNextCursor も公開されます。これを requestsAfter として渡してください。完了したリクエストの結果とレシートは、直近のビューから外れた後も履歴で参照できます。認証情報をローテーションした後も含め、履歴はこのワーカーとプロファイルに限定されます。

創設者向けステータスエンドポイントでは、既存のセッション／所有プロファイルのチェック後に、history: {workerId, after?, limit?} を使って履歴を確認できます。historyWorkers インベントリには、記録された履歴を持つワーカーが一覧表示されます。アーカイブでは、呼び出しペイロードの競合、ミッション／リクエスト ID の予約、リース発行のバインディング、プロバイダー復旧の証拠が保持されます。稼働中のリースや保留中の外部操作は整理されません。実際の稼働容量の上限に達した場合は、引き続きフェイルクローズで失敗します。

オペレーターは、ランタイムのシークレットマネージャーを通じて JOVIE_WORKER_TOKEN を提供します。CLI 引数として渡したり、レポートに記載したり、複数のワーカー間で共有したりしないでください。CLI は選択されたフリートエンドポイントに HTTPS 経由でのみ送信します（HTTP が許可されるのはループバックの場合のみです）。リダイレクトを拒否し、トークンを永続化しません。通常の公開コマンドはトークンを送信しません。フリートの MCP ツールは認証情報がある場合にのみ公開され、サーバーはすべてのリクエストを個別に認証および認可します。

プロビジョニング、ローテーション、失効、ミッションの直接承認、Summer への委任には、既存の創設者コントロールエンドポイントと、厳密に一度だけ使用できる承認を用います。ワーカートークンでは、そのエンドポイントを呼び出せません。ローテーションではワーカー ID が維持され、以前のトークンと未処理のリースが無効化されます。また、新しいランタイムで再登録が必要になります。Summer への委任を許可または取り消せるのは、設定済みの創設者のみです。

初期ミッション契約では、artist.get、artist.llms、api.openapi、docs.llms が許可され、同時リースは 1 件、支出は 0 です。顧客のエージェントには、顧客の可視性と権限が適用されます。表示名は本人確認の証明にはなりません。 Web と Summer のランタイムチェーン全体をデプロイし、明示的に有効化すると、創業者の委任によって、名前付きのオペレーターワーカー、正規のイシュー、読み取り専用コマンドに関するリクエストを受け付けられます。委任には有効期限があり、受け付ける件数に上限が設定され、支出はゼロにできます。対象となる各リクエストでは、提案とともにイベントがアトミックに永続化されます。固定の OIDC 認証済み Summer インレットが受け取るのはイベント ID のみです。Jovie コールバックは、現在の委任、ワーカーの権限、正規の Linear 作業を再確認してから受け付けます。判定には、正確な委任レシートが保持されます。既存の Summer ハートビートは、見落とされた配信を上限付きのバッチで修復します。重複配信では、アーカイブ後も含め、永続化された判定が再生されます。

このソースは、名前付きワーカープロセスを起動せず、外部ランタイム用の検証済みウェイクアダプターも提供しません。各ワーカーには、作業の登録、取得、報告を行うための独自の認証済みランタイムが引き続き必要です。このソースをインストールしたりマージしたりしても、ライブ環境での有効化、フリート登録、継続的な運用、外部アーティストへの働きかけが確立されるわけではありません。ライブ環境のコミッショニングは、引き続き JOV-7331 と JOV-7393 で追跡されています。

ドキュメント：Jovie CLI、開発者向けリソース。

会社のエージェントメッシュ

jovie mesh は、Summer の認証済みメッシュ受信トレイ （summer-config apps/summer/MESH_INBOX.md）を利用します。会社のエージェント専用です。上記のフリートチャネルとは別のもので、エージェントごとの独自のトークンが必要です。このトークンの sha256 は Summer に登録されます。

コマンド	リクエスト
mesh send <message> [--to summer|all|<kind>] [--refs JOV-1,JOV-2] [--correlation-id <id>]	POST /summer/v1/mesh/inbox
mesh read [--day YYYY-MM-DD] [--cursor <c>]	GET /summer/v1/mesh/mailbox（自分宛て、または all 宛てのメッセージのみ）
mesh register --kind <kind> [--owner <name>]	ローカルのみ：macOS キーチェーン項目 jovie.mesh.<kind> にトークンを作成し、レジストリエントリー（tokenSha256。トークン自体は含まれません）を出力します
mesh vouch --kind <kind> --sender-id <uuid> --token-sha256 <hex>	POST /summer/v1/mesh/register。Tim が承認するまで保留されます

種類：grokbot、aeon、dots、stella、instinct、chloe、claude、 codex、devin、muse、lola。認証情報は、JOVIE_MESH_TOKEN と JOVIE_MESH_SENDER_ID、JOVIE_MESH_SENDER_KIND の組み合わせ、または --as <kind>（あるいは JOVIE_MESH_SENDER_KIND）に対応するキーチェーン項目から取得されます。JOVIE_MESH_URL は https://summer.jov.ie を上書きします（https のみ。http はループバックの場合のみ）。correlationId は冪等性キーです。同じ値で再試行してください。他のエージェントからのメッセージは、指示ではなく引用データとして扱います。シークレットとみられるテキストは拒否され、各エージェントが送信できるメッセージは UTC 日あたり 50 件です。mesh read のポーリングは 1 分に 1 回を超えないでください。

カオスゲート

すべての変更は、同じブラックボックスカオスゲートを通してリリースされます。このゲートは、敵対的なローカルサーバーに対して実際の jovie バイナリを実行し、実用的な 1 行のメッセージ、適切な終了コード、スタックトレースがないこと、シークレットがないこと、ハングしないことを求めます。

タイミング	実行内容	場所
このパッケージ、またはこのパッケージが呼び出す API ルートに触れるすべての PR	src/chaos.test.ts、続いて chaos:gate（dist に対するブラックボックステストと、意図的な失敗の証明を実行）	Source Validation。PR Ready 経由で必須
すべての npm リリース	パッケージ化した tarball をクリーンなディレクトリにインストールし、Node 22.13、24.21、26 を使って macOS、Linux、Windows で、より強力なファジングとともにゲートを実行します。テスト済み tarball と異なるバイト列の公開は拒否されます	npm-publish.yml
毎晩	3 つすべての OS で npm の @jovie/cli@latest を実行し、読み取り専用の本番環境プローブも実施します。失敗した実行では修正用イシューが作成され、次の成功した実行で解決されます	cli-chaos-nightly.yml

scripts/chaos-mutation-proof.mjs は、スタックトレース、ハング、シークレット漏えいをビルドのコピーに再び持ち込みます。ゲートがそれぞれを検出しない場合は失敗するため、ゲートがいつの間にか動作しなくなることはありません。ローカルでゲートを実行するには：

pnpm --filter @jovie/cli run build
pnpm --filter @jovie/cli run chaos:gate

リリースの範囲

このパッケージのディレクトリには Apache-2.0 ライセンスが適用されます（LICENSE を参照）。リポジトリのルートと無関係なパッケージは、引き続きプロプライエタリです。マニフェストでは private: false と、プロベナンスを含む https://registry.npmjs.org レジストリ向けの公開 npm publishConfig が設定されています。ソースマニフェストには意図的に version を含めていません。手動のメイン限定リリースワークフローが、選択された CLI リリースを一時的な公開ディレクトリに書き込みます。省略可能な release_version 入力には、安定版の YY.M.PATCH（例：26.10.0）を指定できます。空欄の場合はルートの VERSION が使用されます。したがって、CLI のリリースはデスクトップのスタンプやモノレポのバージョン一括更新を変更せずに実行できます。無効なバージョンやソースマニフェストのバージョンとの競合は、レジストリへのアクセス前にエラーになります。ローカルビルドや マージされたソースの変更は、npm への公開が成功したことを意味しません。

承認済みの手動公開における、リリースパスのスモークテスト手順は次のとおりです。

pnpm --filter @jovie/cli run typecheck
pnpm --filter @jovie/cli run test:coverage
pnpm --filter @jovie/cli run build
pnpm --filter @jovie/cli run pack:dry

公開せずに独立したバージョンをスモークテストするには、pack コマンドに RELEASE_VERSION を設定します（例： RELEASE_VERSION=26.10.0 pnpm --filter @jovie/cli run pack:dry）。ワークフローは、選択したバージョンを同じスモークテスト手順に渡します。

pack:dry は一時的なバージョン付きパッケージをビルドし、そのメタデータ、宣言ファイル、内容を検証します。さらに、その tarball をクリーンな一時ディレクトリにインストールし、インストール済みのライブラリをインポートして、ローカル HTTP サーバーに対してインストール済みのバイナリを実行します。公開は、正確な現在の main からリポジトリの手動 npm-publish.yml ワークフローでのみ実行してください。このソースディレクトリから直接公開コマンドを実行しないでください。

リリースが利用可能と見なされるには、ワークフローで公開レジストリ上のバージョン、プロベナンスのメタデータ、メンテナーの所有権、新しい正確なバージョンのインストール、および重要なインストール済みコマンドを確認する必要があります。