コマンド一覧
`cozeni` の全コマンドとオプション。
cozeni は、商品の作成と更新、購入リンクの取得、販売状態の確認、テスト購入を行うコマンドです。init 以外のコマンドは SDK を依存に入れたあとに npx cozeni <コマンド> で呼びます。出力の形と終了コードは CLI の概要 を、ログインは CLI の認証 を見てください。
コマンド
| コマンド | 説明 |
|---|---|
init |
SDK を依存に追加し、手順書を置き、接続先とクリエイターを保存します。 |
login |
ログインを始めます。承認用の URL とコードを表示します。 |
login --complete |
承認を確かめて、キーを保存します。 |
logout |
キーを失効させ、手元のキーを消します。 |
whoami |
接続先、クリエイター、キーの期限を表示します。 |
status |
販売できる状態か、次にやること、商品の一覧を表示します。 |
products list |
商品の一覧を表示します。 |
products get |
商品1件と購入リンクの状態を表示します。 |
products create |
商品を作成し、購入リンクを返します。 |
products update |
商品の名前、価格、--access-url を変更します。 |
link |
購入リンクを返します。未発行なら発行します。 |
test-purchase |
サンドボックスでテスト購入し、確かめて返金します。 |
switch |
既定の接続先を本番に切り替えます。 |
help |
--help と同じ使い方の案内を表示します。 |
書式
npx cozeni <コマンド> [--json] [--profile <名前>] [--yes]
共通オプション
| オプション | 意味 |
|---|---|
--json |
結果を1行の JSON で標準出力に出します。AI エージェントや自動化向けです。 |
--profile <名前> |
接続先を選びます。通常は production(本番)か sandbox(サンドボックス)です。開発用には独自の名前も使えます。省略すると、init で選んだ既定の接続先を使います。init をしていなければ production です。 |
--api-origin <URL> |
開発用の API のオリジンです。独自の名前のプロファイルで使います。 |
--app-origin <URL> |
開発用の管理画面のオリジンです。独自の名前のプロファイルで使います。 |
--yes |
確認を省略します。products create と products update でだけ使えます。 |
--help、-h |
使い方を表示します。 |
--version、-v |
CLI のバージョンを表示します。 |
独自のプロファイルは Nulogic の開発用です。名前は英小文字か数字で始め、英小文字・数字・-・_ の32文字以内にします。初回の init で --profile <名前>、--api-origin、--app-origin、--creator を指定すると、接続先を保存します。以後は --profile <名前> で選べます。API の接続先は、--api-origin、環境変数 COZENI_API_ORIGIN、保存した値の順に使います。production と sandbox の接続先は固定で、これらの指定で別のオリジンへ変えることはできません。
init
サイトのプロジェクトのフォルダで実行します。SDK を依存に追加し、AI エージェント向けの手順書(cozeni-setup)を .agents/skills/ に置きます。Claude Code から実行したときと、プロジェクトに .claude フォルダがあるときは .claude/skills/ にも置きます。既定の接続先とクリエイターを保存します。何度実行してもかまいません。ログインは不要です。
npx @nulogic/cozeni-sdk@0.8.0 init --creator cre_... --json
| オプション | 意味 |
|---|---|
--creator <クリエイターID> |
cre_ で始まるクリエイターIDです。初回は必須です。管理画面の導入プロンプトに書かれています。 |
--profile <名前> |
通常は production か sandbox です。開発用の独自の名前も使えます。sandbox を指定すると、導入はテスト購入までで止まります(本番への切り替えは行いません)。 |
--json |
結果を JSON で出します。 |
--profile を省略して --creator を渡すと、既定の接続先がサンドボックスになり、そのクリエイターIDが本番用に保存されます。これは本番の管理画面から取った導入プロンプトの流れです。詳しくは サンドボックス を見てください。
--json の成功出力の data は次の項目を含みます。
| 項目 | 内容 |
|---|---|
project_root、package_manager |
SDK を入れたプロジェクトの場所と、使ったパッケージマネージャーです。 |
sdk |
name、version、installed です。installed は今回 SDK をインストールしたかを示します。 |
skills |
置いた手順書の一覧です。各項目に path と status(created、updated、unchanged)があります。 |
profile、api_origin、app_origin |
保存した既定の接続先の名前、API と管理画面のオリジンです。 |
expected_creator_id |
その接続先で照合するクリエイターIDです。本番からサンドボックスでの導入を始める場合は null です。 |
production_expected_creator_id |
本番からサンドボックスでの導入を始める場合だけ返る、本番のクリエイターIDです。 |
config_path、next_step |
設定ファイルの場所と、次にすることです。 |
login
承認用の URL とコードを表示して、すぐに終わります。ブラウザで承認したあとに login --complete を実行します。
npx cozeni login --json
| オプション | 意味 |
|---|---|
--profile <名前> |
ログインする接続先です。 |
--json |
結果を JSON で出します。 |
保存済みのキーがまだ使え、期待するクリエイターと一致し、期限まで7日以上あるときは、承認を求めずに成功します(data.already_logged_in が true)。
承認を始めると、data に verification_uri(承認用の URL)、user_code(表示用のコード)、expires_at(期限)、next_step が入ります。コードを含む承認用の URL を返すときは、verification_uri_complete も入ります。保存済みのキーを使う場合は、次の login --complete と同じアカウント・キーの情報を返し、already_logged_in が true になります。
login --complete
ブラウザでの承認を確かめて、キーを保存します。最長90秒待ちます。
npx cozeni login --complete --json
| 結果 | 終了コード | 次にすること |
|---|---|---|
| 保存できた | 0 | 続けて status を実行します。 |
まだ承認されていない(authorization_pending) |
6 | 利用者の承認を待ち、同じコマンドを打ち直します。 |
| 拒否された、またはコードの期限が切れた | 3 | login からやり直します。 |
別のアカウントで承認された(creator_mismatch) |
4 | 正しいアカウントでブラウザにログインし直してから、login からやり直します。 |
導入の流れが本番の管理画面から始まっていた場合は、--profile production で成功すると、既定の接続先も本番に切り替わります(data.switched_to_production が true)。
成功出力の data は次の項目を含みます。キーの値は含みません。
| 項目 | 内容 |
|---|---|
already_logged_in |
新しいキーを保存した場合は false、保存済みのキーを使う login では true です。 |
profile、api_origin、environment |
接続先の名前、API のオリジン、サーバーが返した環境名です。 |
creator_id、key_id |
クリエイターとキーのIDです。 |
expires_at、credentials_path |
キーの期限と、保存した認証情報ファイルの場所です。 |
warnings |
警告の配列です。旧キーの失効に失敗した場合は previous_key_not_revoked、環境変数のキーが優先される場合は env_key_takes_precedence が入ります。 |
next_step |
次にすることです。 |
本番への切り替えが完了した場合は default_profile: "production" と switched_to_production: true も返します。ログインには成功しても、導入の設定を確認できず切り替えなかった場合は switch_aborted: true が入ります。その場合は next_step に従ってください。警告が出た場合の扱いは CLI の認証 を見てください。
logout
サーバーでキーを失効させ、手元に保存したキーを消します。サーバーでの失効に失敗したときは、警告を出して、手元に保存したキーは消します。COZENI_API_KEY のキーは失効させません。
npx cozeni logout --json
成功出力の data は、profile、removed(保存したキーを削除したか)、revoked(サーバーで失効できたか)、warnings です。warnings には、サーバーで失効できなかった場合の server_revoke_failed と、環境変数のキーを失効させていないことを示す env_key_not_revoked が入ることがあります。
whoami
接続先とクリエイター、キーの情報を表示します。キーの値は出しません。
npx cozeni whoami --json
data の項目 |
意味 |
|---|---|
profile |
使っているプロファイルです。 |
api_origin |
接続先の API のオリジンです。 |
environment |
接続先の環境名です。本番は production、サンドボックスは sandbox です。 |
creator_id |
クリエイターのIDです。 |
key_id |
キーのIDです。キーの値ではありません。 |
key_source |
saved(ログインで保存したキー)か env(COZENI_API_KEY)です。 |
expires_at |
保存したキーの期限です。環境変数のキーでは null です。 |
scopes |
キーのスコープです。 |
expected_creator_id |
init で保存した、この接続先で使うはずのクリエイターIDです。無ければ null です。 |
status
販売できる状態かを確かめ、次にやることと商品の一覧を表示します。困ったときは、まずこのコマンドを実行します。
npx cozeni status --json
data の項目 |
意味 |
|---|---|
profile、api_origin、environment |
接続先の名前、API のオリジン、環境名です。 |
creator_id、expected_creator_id |
実際のクリエイターと、照合するはずのクリエイターのIDです。期待値が無ければ expected_creator_id は null です。 |
key |
id、source(saved か env)、expires_at を含みます。環境変数のキーでは期限が null です。キーの値は含みません。 |
sales |
販売状態です。can_sell(販売できるか)、blockers(販売を始めるまでの手続き)、warnings を含みます。接続先が対応していない場合は null です。 |
next_actions |
手続きごとの案内と、手続きを行う action_url です。 |
message_for_user |
利用者にそのまま見せられる「次にやること」の行です。販売できるときは「すぐ販売できます。」です。 |
products |
商品の一覧です。 |
warnings |
key_expiring(ログインの期限が7日以内)、test_purchase_not_refunded(返金していないテスト購入がある)を含みます。 |
unrefunded_test_purchases |
返金していないテスト購入の商品IDです。test-purchase --product <商品ID> --refund で返金します。 |
next_step |
次に実行するコマンドです。無ければ null です。 |
products list
商品の一覧を表示します。data.items に商品が入ります。
npx cozeni products list --json
products get
商品1件と購入リンクの状態を表示します。購入リンクは取得するだけで、発行はしません。購入リンクが未発行のときは、data.next_step に link の実行を示します。
npx cozeni products get prd_... --json
data.product に商品、data.checkout_link に購入リンク、data.next_step に次にすることが入ります。未発行なら checkout_link は null です。
products create
商品を作成し、標準の購入リンクを返します。作成には --name、--price、そして --access-url か --feature のどちらか一方が必要です。
npx cozeni products create --name "限定ハンドブック" --price 1000 --access-url "https://example.com/members" --yes --json
| オプション | 意味 |
|---|---|
--name <名前> |
商品名です。必須です。前後の空白は除かれます。 |
--price <円> |
価格です。必須です。50から9,999,999までの整数(円)で指定します。 |
--access-url <URL> |
購入後に表示するページのURLです。限定ページの商品に使います。--feature と一緒には使えません。 |
--feature |
機能フラグの商品にします。--access-url の代わりに使います。作成後に種類は変えられません。 |
--metadata <key=value> |
機能フラグの設定値です。繰り返し指定できます。--feature のときだけ使えます。値が true か false なら真偽値、数字なら数値、それ以外は文字列になります。 |
--allow-duplicate |
同じ内容の有効な商品があっても、別の商品として作ります。 |
--yes |
確認を省略します。非対話の実行では必須です。 |
同じ名前・価格・--access-url(機能フラグでは設定値)の有効な商品があれば、作らずにそれを返します(data.reused が true、data.reason が same_product_exists)。同じコマンドを再実行しても、商品は二重に作られません(data.reason が idempotent_retry)。
成功出力の data は、product(商品)、checkout_link(購入リンク)、reused(既存の商品を返したか)、next_step です。reused が true の場合は、上の reason も入ります。
products update
商品の名前、価格、--access-url を変更します。少なくとも1つ指定します。
npx cozeni products update prd_... --price 1200 --yes --json
| オプション | 意味 |
|---|---|
--name <名前> |
商品名を変えます。 |
--price <円> |
価格を変えます。範囲は products create と同じです。 |
--access-url <URL> |
購入後に表示するページを変えます。既存のお客様にもすぐ反映されます。 |
--yes |
確認を省略します。価格か --access-url を変えるときは、非対話の実行で必須です。名前だけを変えるときは確認を求めません。 |
機能フラグの設定値(metadata)はこのコマンドでは変えられません。
成功出力の data.product に、更新後の商品が入ります。
link
商品の標準の購入リンクを返します。products get と違い、未発行なら発行します。
npx cozeni link prd_... --json
成功出力の data.checkout_link に購入リンクが入ります。商品や購入リンクの項目は、API リファレンス の応答と同じです。
test-purchase
サンドボックスでテスト購入し、結果を確かめて返金します。本番のプロファイルでは使えません(終了コード2)。
npx cozeni test-purchase --profile sandbox --product prd_... --site-origin http://localhost:3000 --json
| オプション | 意味 |
|---|---|
--product <商品ID> |
商品IDです。必須です。 |
--site-origin <URL> |
限定ページの商品で必要です。開発サーバーのオリジンを指定します。localhost、127.0.0.1、[::1] のいずれかだけ使えます。機能フラグの商品では不要です。 |
--refund |
テスト購入を返金します。機能フラグの商品で、利用者が確かめたあとに使います。 |
限定ページの商品では、開発サーバーの限定ページに入れることと、未購入のときに Cozeni の入場画面へ送られることを確かめてから返金します。機能フラグの商品では、付与された設定値を確かめて止まります。--refund で別に返金します。ファイルの商品では使えません(invalid_input)。
成功出力の data は、商品の種類や --refund の有無で項目が変わります。
| 項目 | 含まれる結果と意味 |
|---|---|
profile、product_id |
すべての成功結果。接続先と対象の商品IDです。 |
site_origin |
限定ページの確認。確認に使った開発サーバーのオリジンです。 |
entered |
限定ページの確認。購入後に入れたことを示す true です。 |
redirected_when_unpurchased |
限定ページの確認。未購入では入場画面へ送られたことを示す true です。 |
access_type、granted、metadata |
機能フラグの確認。access_type は "feature"、granted は true、metadata は付与された設定値です。 |
refunded |
すべての成功結果。返金した場合は true です。機能フラグの確認で返金せず止まった場合や、返金の対象が無かった場合は false です。 |
refund_count |
限定ページの確認と --refund。返金した注文の件数です。対象が無ければ 0 です。 |
next_step |
--refund を付けない確認。利用者への案内や、次にすることです。 |
| 終了コード | 意味と対処 |
|---|---|
| 2 | 本番のプロファイル(test_purchase_unavailable)、またはループバック以外の --site-origin(site_origin_not_allowed)です。送らずに止まります。 |
| 4 | 売上の受け取り先の登録が済んでいない(creator_not_ready)、または限定ページの確認に失敗した(entry_check_failed)です。error.hint に従います。 |
| 5 | 開発サーバーに届かない(site_unreachable)です。起動を確かめて、打ち直します。テスト決済の処理に失敗した(stripe_error)ときも、打ち直します。 |
| 6 | 待ち時間内に購入権が確定しませんでした。同じコマンドを打ち直します。処理中の決済があれば、新たに決済しません。 |
switch
本番にログイン済みで、期待するクリエイターと一致していれば、既定の接続先を本番に切り替えます。本番の管理画面から取った導入プロンプトで始めた導入だけが対象です。サンドボックスから始めた導入では、invalid_input(終了コード2)で止まります。
npx cozeni switch --json
成功出力の data は、switched(今回切り替えたか)、default_profile("production")、previous_profile(切り替え前の既定)、creator_id、environment("production")、next_step です。すでに本番が既定の場合は switched: false になります。