---
title: コマンド一覧
description: "`cozeni` の全コマンドとオプション。"
---

`cozeni` は、商品の作成と更新、購入リンクの取得、販売状態の確認、テスト購入を行うコマンドです。`init` 以外のコマンドは SDK を依存に入れたあとに `npx cozeni <コマンド>` で呼びます。出力の形と終了コードは [CLI の概要](/integrate/cli) を、ログインは [CLI の認証](/integrate/cli/authentication) を見てください。

## コマンド

| コマンド | 説明 |
| --- | --- |
| [`init`](#init) | SDK を依存に追加し、手順書を置き、接続先とクリエイターを保存します。 |
| [`login`](#login) | ログインを始めます。承認用の URL とコードを表示します。 |
| [`login --complete`](#login---complete) | 承認を確かめて、キーを保存します。 |
| [`logout`](#logout) | キーを失効させ、手元のキーを消します。 |
| [`whoami`](#whoami) | 接続先、クリエイター、キーの期限を表示します。 |
| [`status`](#status) | 販売できる状態か、次にやること、商品の一覧を表示します。 |
| [`products list`](#products-list) | 商品の一覧を表示します。 |
| [`products get`](#products-get) | 商品1件と購入リンクの状態を表示します。 |
| [`products create`](#products-create) | 商品を作成し、購入リンクを返します。 |
| [`products update`](#products-update) | 商品の名前、価格、`--access-url` を変更します。 |
| [`link`](#link) | 購入リンクを返します。未発行なら発行します。 |
| [`test-purchase`](#test-purchase) | サンドボックスでテスト購入し、確かめて返金します。 |
| [`switch`](#switch) | 既定の接続先を本番に切り替えます。 |
| `help` | `--help` と同じ使い方の案内を表示します。 |

## 書式

```sh
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` の接続先は固定で、これらの指定で別のオリジンへ変えることはできません。

:::note
`switch` には `--json` とヘルプ表示の `--help` を付けられます。`--profile` と `--yes` は付けられません。`products create` と `products update` 以外で `--yes` を付けると、`invalid_input`（終了コード2）で止まります。
:::

## init

サイトのプロジェクトのフォルダで実行します。SDK を依存に追加し、AI エージェント向けの手順書（`cozeni-setup`）を `.agents/skills/` に置きます。Claude Code から実行したときと、プロジェクトに `.claude` フォルダがあるときは `.claude/skills/` にも置きます。既定の接続先とクリエイターを保存します。何度実行してもかまいません。ログインは不要です。

```sh
npx @nulogic/cozeni-sdk@0.8.0 init --creator cre_... --json
```

| オプション | 意味 |
| --- | --- |
| `--creator <クリエイターID>` | `cre_` で始まるクリエイターIDです。初回は必須です。管理画面の導入プロンプトに書かれています。 |
| `--profile <名前>` | 通常は `production` か `sandbox` です。開発用の独自の名前も使えます。`sandbox` を指定すると、導入はテスト購入までで止まります（本番への切り替えは行いません）。 |
| `--json` | 結果を JSON で出します。 |

`--profile` を省略して `--creator` を渡すと、既定の接続先がサンドボックスになり、そのクリエイターIDが本番用に保存されます。これは本番の管理画面から取った導入プロンプトの流れです。詳しくは [サンドボックス](/integrate/sandbox) を見てください。

`--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` を実行します。

```sh
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秒待ちます。

```sh
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 の認証](/integrate/cli/authentication) を見てください。

## logout

サーバーでキーを失効させ、手元に保存したキーを消します。サーバーでの失効に失敗したときは、警告を出して、手元に保存したキーは消します。`COZENI_API_KEY` のキーは失効させません。

```sh
npx cozeni logout --json
```

成功出力の `data` は、`profile`、`removed`（保存したキーを削除したか）、`revoked`（サーバーで失効できたか）、`warnings` です。`warnings` には、サーバーで失効できなかった場合の `server_revoke_failed` と、環境変数のキーを失効させていないことを示す `env_key_not_revoked` が入ることがあります。

## whoami

接続先とクリエイター、キーの情報を表示します。キーの値は出しません。

```sh
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

販売できる状態かを確かめ、次にやることと商品の一覧を表示します。困ったときは、まずこのコマンドを実行します。

```sh
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` に商品が入ります。

```sh
npx cozeni products list --json
```

## products get

商品1件と購入リンクの状態を表示します。購入リンクは取得するだけで、発行はしません。購入リンクが未発行のときは、`data.next_step` に `link` の実行を示します。

```sh
npx cozeni products get prd_... --json
```

`data.product` に商品、`data.checkout_link` に購入リンク、`data.next_step` に次にすることが入ります。未発行なら `checkout_link` は `null` です。

## products create

商品を作成し、標準の購入リンクを返します。作成には `--name`、`--price`、そして `--access-url` か `--feature` のどちらか一方が必要です。

```sh
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つ指定します。

```sh
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` と違い、未発行なら発行します。

```sh
npx cozeni link prd_... --json
```

成功出力の `data.checkout_link` に購入リンクが入ります。商品や購入リンクの項目は、[API リファレンス](/api-reference) の応答と同じです。

## test-purchase

サンドボックスでテスト購入し、結果を確かめて返金します。本番のプロファイルでは使えません（終了コード2）。

```sh
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）で止まります。

```sh
npx cozeni switch --json
```

成功出力の `data` は、`switched`（今回切り替えたか）、`default_profile`（`"production"`）、`previous_profile`（切り替え前の既定）、`creator_id`、`environment`（`"production"`）、`next_step` です。すでに本番が既定の場合は `switched: false` になります。
