CLI移行ガイド (v2→v3)

このガイドでは @orizm/cli v2 から v3 への移行方法を説明します。

v3 には破壊的変更が含まれます。OAuth2 認証への移行、.env ファイルの自動読み込み廃止、プロジェクトコンテキストの .orizm/project.json への移行、コマンド体系の変更、生成コードの構造変更（types.ts の廃止）が行われました。

`orizm auth login` への切替

v3 では OAuth2 認証が基本になります。ブラウザでログインし、トークンをローカルに保存して以降のコマンドで利用します。

ログインする


orizm auth login

デフォルトブラウザが起動して認証画面が開きます。認証が完了すると、トークンが ~/.config/orizm/auth.json（Windows は %APPDATA%/orizm/auth.json）に保存されます。

ログイン状態を確認する


orizm auth status

ログイン中のユーザーや接続先を表示します。

ログアウトする


orizm auth logout

ローカルのトークンを破棄します。

`.env` の自動読み込み廃止と API キーの継続利用

v2 では CLI が .env ファイルを自動で読み込んでいましたが、v3 では .env の自動読み込みを廃止 しました。

CI や自動化スクリプトで API キーを使い続ける場合は、ORIZM_API_KEY を環境変数として明示的に設定してください。OAuth2 トークンが存在しない場合に API キー認証へフォールバックします。

GitHub Actions では次のように設定します。

.github/workflows/example.yml


- run: orizm schema push --yes
  env:
    ORIZM_API_KEY: ${{ secrets.ORIZM_API_KEY }}

ローカルで引き続き .env を使いたい場合は、dotenv-cli や direnv などのラッパーを利用してください。


dotenv -e .env -- orizm schema push

`.orizm/project.json` への移行

v3 ではプロジェクトコンテキストを .orizm/project.json で管理します（Vercel CLI の vercel link と同じ方式）。

orizm link を実行すると、所属する Organization と Project を対話的に選択して .orizm/project.json を生成します。初回実行時には .gitignore への .orizm/ の追記を促されます。


orizm link

CI など対話できない環境では、ORIZM_PROJECT 環境変数または --project フラグでプロジェクトを指定します。プロジェクトコンテキストは次の順序で解決されます。

--project <name> フラグ
ORIZM_PROJECT 環境変数
.orizm/project.json の projectName

生成コードの構造変更（`types.ts` の廃止）

v2 の orizm cms generate / orizm consumer generate は、出力先ディレクトリに types.ts（型定義）と client.ts（クライアント）の 2 ファイル を生成していました。client.ts は import * as Models from "./types" で types.ts の型を参照する構造です。

v3 の orizm codegen cms / orizm codegen consumer は、型定義とクライアントを単一のファイルに統合 して出力します。types.ts は生成されなくなり、型は生成ファイルから直接 export されます。

型定義の内容（プロパティ名や __Descriptor などの構造）は v2 と v3 で同一です。変わったのは「型がどのファイルに置かれ、どこから import するか」だけなので、移行は出力先の指定と import 文の調整で完結します。

v2 が生成した types.ts は v3 では 更新されません。古いまま残すとスキーマ変更が型に反映されず実体と乖離するため、移行時に必ず削除してください。

出力先に単一ファイルを指定する

v3 では --output に出力ファイルのパスを指定します。v2 で client.ts を出力していたディレクトリの client.ts をそのまま指定すると、クライアントの import 元（./orizm/client）を変えずに済みます。


orizm codegen cms --output src/orizm/client.ts
orizm codegen consumer --output src/lib/orizm/client.ts

`types.ts` からの import を生成ファイルに置き換える

型を types.ts から import していた箇所を、生成ファイル（client.ts）からの import に変更します。


- import { Article, ArticleCreateInput } from "./orizm/types";
+ import { Article, ArticleCreateInput } from "./orizm/client";

クライアント本体（CMSClient / OrizmClient）の import 元は v2 と同じ client.ts のままで変更不要です。

古い `types.ts` を削除する

import の置き換えが終わったら、v2 が生成した types.ts を削除します。


rm src/orizm/types.ts

接続先の環境変数

接続先を切り替えるための環境変数は次のとおりです。

環境変数	用途	デフォルト
`ORIZM_BASE_URL`	Developer API の base URL。ローカル / staging / production を切り替える	`https://app.orizm.com`
`ORIZM_OAUTH_ISSUER_URL`	OAuth2 認証サーバーの URL。本番 / staging は通常省略。ローカルで認証サーバーが別ポートのときだけ指定する	`ORIZM_BASE_URL` と同じ

旧→新コマンド対応表

コマンドは noun-first 体系（orizm <noun> <verb>）へ整理されました。v2 のコマンドは次のように変わります。

v2	v3
`orizm push`	`orizm schema push`
`orizm cms generate`	`orizm codegen cms`
`orizm cms pull`	`orizm codegen cms --pull`
`orizm consumer generate`	`orizm codegen consumer`
`orizm consumer pull`	`orizm codegen consumer --pull`
`orizm config validate`	`orizm schema validate`
`orizm config generate-erd`	`orizm schema erd`