コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

CLI の概要

ターミナルと AI エージェントから Cozeni を操作する `cozeni` コマンド。

cozeni は、商品の作成と更新、購入リンクの取得、販売状態の確認、テスト購入を、ターミナルや AI エージェントから行うコマンドです。SDK に同梱されていて、npx @nulogic/cozeni-sdk@<バージョン> init で導入します。

使いどころ

  • AI エージェントが商品を作成し、購入リンクを発行し、テスト購入する。
  • 商品の価格や --access-url を、コードを書かずに変える。
  • 販売状態(販売できるか、次に何をするか)を確かめる。

サイトのコードに組み込む部分は、SDK で書きます。

動く条件

  • Node.js 20 以上で動きます。
  • サイトのプロジェクトの中で使います。init が SDK をプロジェクトの依存に入れ、以後の npx cozeni はプロジェクトに入った SDK の CLI を実行します。

はじめる

サイトのプロジェクトのフォルダ(package.json のある場所)で、次の順に実行します。

npx @nulogic/cozeni-sdk@0.8.0 init --creator cre_... --json
npx cozeni login --json
npx cozeni login --complete --json
npx cozeni status --json
  1. init で SDK を依存に追加し、AI エージェント向けの手順書を置きます。
  2. login でコードと承認用の URL を表示し、利用者がブラウザで承認します。
  3. login --complete で承認を確かめて、キーを保存します。
  4. status で販売できる状態かを確かめます。

init の後に npx cozeni が「Cozeni の SDK がこのプロジェクトに入っていません。」と表示されて止まるときは、SDK がプロジェクトの依存に入っていません。プロジェクトのフォルダで init を打ち直してください。

コマンド一覧ではすべてのコマンドとオプションを説明しています。ログインではキーの種類と保存先を説明しています。

バージョンを上げる

init は、実行したバージョンの SDK を、バージョンを固定してプロジェクトの依存に入れます。npx cozeni が使う CLI のバージョンは、このプロジェクトの依存のバージョンです。今のバージョンは npx cozeni --version で確かめられます。

バージョンを上げるときは、新しいバージョンを指定して、プロジェクトのフォルダで init を打ち直します。

npx @nulogic/cozeni-sdk@<新しいバージョン> init --json
  • --profile と --creator を省略すると、今の既定の接続先とクリエイターを引き継ぎます。
  • init は依存のバージョンを差し替え、AI エージェント向けの手順書も新しいバージョンのものに置き換えます。
  • 手順書が対応するバージョンと CLI のバージョンが合わないと、CLI は警告を出して、init での更新を促します。処理は止まりません。

出力と終了コード

--json を付けると、結果が1行の JSON で標準出力に出ます。

{"ok":true,"data":{"next_step":"npx cozeni login --complete"}}

失敗したときは、ok が false になり、error に code、message、hint が入ります。

{"ok":false,"error":{"code":"login_required","message":"Cozeni にログインしていません。","hint":"npx cozeni login を実行してください。"}}

AI エージェントは、成功したら data.next_step を、失敗したら error.hint を見て次の行動を決めます。

終了コード 意味 代表的な error.code
0 成功 —
1 想定外のエラー internal、invalid_response、install_failed、package_manager_conflict、unsafe_path、insecure_storage、invalid_state
2 使い方の誤り、確認が必要、接続先の不一致 invalid_input、confirmation_required、cancelled、origin_mismatch、environment_mismatch、test_purchase_unavailable、site_origin_not_allowed
3 ログインが必要 login_required、key_expired、access_denied、expired_token
4 権限、規約、状態で拒否 terms_consent_required、forbidden、not_found、product_archived、checkout_link_disabled、idempotency_conflict、creator_mismatch、creator_not_ready、entry_check_failed
5 通信できない、一時的な障害 network_unreachable、unexpected_redirect、rate_limited、stripe_error、unavailable、site_unreachable
6 承認待ち、または購入権の確定待ち authorization_pending

ここに無いコードは終了コード1になります。rate_limited のときは、error.retry_after_seconds の秒数を待ってから、同じコマンドを実行します。

確認が必要な操作

商品の作成、価格の変更、購入後に表示するページ(access_url)の変更は、確認を経てから実行されます。

  • 人が直接実行しているときは、CLI が変更の内容を示して確認を求めます。
  • AI エージェントや --json の実行では、確認を求めずに confirmation_required(終了コード2)で止まります。確認の内容は error.details に入ります。
  • 利用者の確認を得てから、--yes を付けて同じコマンドを実行します。

access_url の変更は既存のお客様全員にすぐ反映されます。名前だけの変更は確認なしで実行されます。

次に読むページ

このページは役に立ちましたか?