---
title: CLI の概要
description: ターミナルと AI エージェントから Cozeni を操作する `cozeni` コマンド。
---

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

## 使いどころ

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

サイトのコードに組み込む部分は、[SDK](/integrate/sdk) で書きます。

## 動く条件

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

## はじめる

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

```sh
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` を打ち直してください。

[コマンド一覧](/integrate/cli/reference)ではすべてのコマンドとオプションを説明しています。[ログイン](/integrate/cli/authentication)ではキーの種類と保存先を説明しています。

## バージョンを上げる

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

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

```sh
npx @nulogic/cozeni-sdk@<新しいバージョン> init --json
```

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

## 出力と終了コード

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

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

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

```json
{"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` の変更は既存のお客様全員にすぐ反映されます。名前だけの変更は確認なしで実行されます。

## 次に読むページ

**[コマンド一覧](/integrate/cli/reference)**

すべてのコマンドとオプションを説明します。

**[ログイン](/integrate/cli/authentication)**

ログインの流れと、キーの種類と保存先を説明します。

**[AI エージェントで組み込む](/integrate/ai-agents)**

導入プロンプトを使って、エージェントに組み込ませる流れを説明します。

**[サンドボックス](/integrate/sandbox)**

テスト購入と、本番への切り替えを説明します。
