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
initで SDK を依存に追加し、AI エージェント向けの手順書を置きます。loginでコードと承認用の URL を表示し、利用者がブラウザで承認します。login --completeで承認を確かめて、キーを保存します。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 の変更は既存のお客様全員にすぐ反映されます。名前だけの変更は確認なしで実行されます。