appwrite-cli

Appwrite CLI

appwrite <command> --help にはすでにフラグが一覧表示されます。推測せず、これを読んでください。

設定と client の違い

実際のプロジェクト（リポジトリ、スキーマ、関数、デプロイ、CI）は appwrite.config.json に置きます。最初に一度だけ init します。以降は pull と push を行います。すべてのコマンドで appwrite client --project-id を実行しないでください。設定ファイルにすでにプロジェクトが記載されています。

単発の操作（ユーザーの確認、1 行の修正、もう戻ることのないリモートへのアクセス）では appwrite client を使用します。単一の API 呼び出しのためにプロジェクトを雛形から作らないでください。

# Good — project
appwrite login
appwrite list-projects --json
appwrite init project --project-id <ID>
appwrite pull table
# edit appwrite.config.json, then:
appwrite push table --force

# Bad — project treated as a pile of API calls
appwrite tablesdb create-table --database-id main --table-id songs ...
appwrite tablesdb create-varchar-column --database-id main --table-id songs ...
# the next clone has no record of this

# Good — one-off (already logged in)
appwrite client --project-id <ID>
appwrite users get --user-id <ID> --json

# Bad — one-off that litters a repo
cd ~/some-unrelated-app && appwrite init project

セッションがありませんか？ appwrite client --endpoint https://<REGION>.cloud.appwrite.io/v1 --key "$APPWRITE_API_KEY" --project-id <ID> を実行してください。

appwrite client --project-id はこのディレクトリに appwrite.config.json を書き込みます（または上位ディレクトリをたどって見つかったものを更新します）。これがフォルダーを素早くリンクする方法です。無関係なリポジトリのルートで実行しないでください。APPWRITE_PROJECT_ID / APPWRITE_ENDPOINT はファイルに触れずに上書きします。すでにプロジェクト内にいて、別の対象に対して一度だけ実行する必要がある場合はこちらを使用してください。

認証はプロジェクトではない

レイヤー	保存場所	設定方法
あなたが誰か（セッションまたは API キー）	CLI のグローバル設定	appwrite login または appwrite client --key
どのプロジェクトか	appwrite.config.json	init project、pull、または client --project-id

init project はコンソールと通信します。ログインセッションが必要です。API キーでは組織を一覧表示できません。

# Good — CI against a checked-in config
appwrite client --key "$APPWRITE_API_KEY"
appwrite push function --force

# Bad — CI that bakes the key into the repo
appwrite client --key 'standard_....'
# and commits appwrite.config.json with secrets inside

環境変数は設定ファイルより優先されます: APPWRITE_PROJECT_ID、APPWRITE_ENDPOINT、APPWRITE_ORGANIZATION_ID。設定ファイルはバージョン管理に含めてください（シークレットは含めません）。キーは環境変数に置いてください。

--force はプロンプトをスキップします。エージェントや CI には TTY がないため、確認が必要な push はこれなしでは失敗します（Pass --force instead）。ユーザーに確認してから --force を渡してください。ローカル列が空の変更テーブルをスキップするために使用しないでください。

appwrite login --switch は保存されたアカウントを切り替えます。appwrite client --debug は有効なエンドポイント/プロジェクトを認証情報をマスクして出力します。appwrite client --reset はすべてからサインアウトします。

クラウドエンドポイント

appwrite whoami が https://cloud.appwrite.io/v1 を表示する場合、それはアカウントのログインホストです。そのままにしてください。プロジェクトの API 呼び出しにはリージョンホスト（https://fra.cloud.appwrite.io/v1 など）を使用します。init project と client --project-id はそのリージョンを設定ファイルに固定します。セルフホスト可能な場合: 両方に 1 つのエンドポイントを使用します。

# Good — project work uses the config's regional endpoint
cat appwrite.config.json   # "endpoint": "https://fra.cloud.appwrite.io/v1"

# Bad — "fixing" whoami
appwrite client --endpoint https://fra.cloud.appwrite.io/v1
# now login/session calls go to a region host they do not belong on

スキーマと行

Pull / push（設定）	サービスコマンド（設定に含まれない）
settings、functions、sites、tables と columns、buckets、teams、webhooks、topics	rows、users、files、executions、messages

新しくクローンしても残るべきものであれば、設定ファイルに含めるべきです。ファイルを編集してから push してください。tablesdb create-* や functions create で同じリソースを作成すると、次の pull / push が期待するファイルをバイパスしてしまいます。

databases は非推奨です。tablesdb と push table を使用してください。

変更テーブルでローカルが空のままリモートの値が表示される場合、設定ファイルにそれらのフィールドが欠けています。そのリソースを pull してから push してください。--force で押し通さないでください。また、儀式的にすべてを pull しないでください — pull settings は遅いです。

   id            │ key             │ remote │ local
  ───────────────┼─────────────────┼────────┼───────
   Service       │ account         │ true   │
   Auth method   │ email-password  │ true   │

# Good — local column was empty, so sync first, then push
appwrite pull settings
appwrite push settings --force

# Bad — empty local, forced through
appwrite push settings --force

push all --all --force はすべてのリソースを push します。そのつもりでない限り、スコープを絞ってください（push function --function-id api）。

unique() は単発の行やユーザーには問題ありません。push するリソースには、次の pull が一致できるように設定ファイル内で安定した $id が必要です。

型安全なアプリケーションコード

TablesDB に対してアプリケーションコードを書くときは、インターフェースやデータベース ID、テーブル ID、カラム名を勝手に決める前に appwrite.config.json を確認してください。ジェネレーターはローカルの設定を読み取るのであり、リモートのスキーマを検査するわけではありません。古い設定は古いコードを生み出します。

リモートのスキーマが信頼できる情報源であるなら、まず appwrite pull table で設定を更新してください。プッシュしていないローカルのスキーマ編集の上に pull しないでください。ローカルの設定の方が進んでいる場合は、そのままの状態で生成してください。

TypeScript では、appwrite generate を推奨します。これは完全な TablesDB ラッパーを出力します。データベースとテーブルの選択、create/update のペイロード、返される行、クエリのフィールド、クエリの値が TypeScript によってチェックされます。これは生成されたモデルインターフェースだけを使うよりも強力です。

appwrite generate

生の文字列 ID や手書きのペイロード型に戻るのではなく、生成された API を使用してください。

import { databases, type Songs } from "./generated/appwrite/index.js";

// Database lookup uses its ID; table lookup uses its name from the config.
const songs = databases.use("main").use("Songs");

const page = await songs.list({
  queries: (query) => [
    query.equal("published", true),
    query.orderDesc("createdAt"),
    query.limit(20),
  ],
});

const first: Songs | undefined = page.rows[0];

その例の中のリテラルを推測しないでください。生成された型か設定を読んでください。特に、テーブルに対する .use() はその name を受け取りますが、これは $id と異なる場合があります。スペルミスのあるテーブル、カラム、または誤ったクエリの値をコンパイルで検出させてください。生成後はプロジェクトの型チェッカーを実行してください。

generate は現在、TypeScript 向けの完全なラッパーを提供します。インストールされている Appwrite パッケージからクライアント用かサーバー用かを検出します。サーバー出力は APPWRITE_API_KEY を読み取ります。このキーを生成された定数に含めたり、コミットしたりしないでください。言語、インポート元、モジュール拡張子、クライアント/サーバーモードを上書きするのは、検出が誤っている場合だけにしてください。これらのフラグについては appwrite generate --help を読んでください。

別の対応言語の場合、またはプロジェクトが通常の SDK を意図的に直接使用する場合は、appwrite types <output-directory> を使用してください。TypeScript (ts)、JavaScript (js)、PHP (php)、Kotlin (kotlin)、Swift (swift)、Java (java)、Dart (dart)、C# (cs) に対応しています。これらの短い値を --language に渡してください。typescript や csharp といった名前は、このコマンドが受け付ける値ではありません。生成されたファイルは行データに型を付けますが、生のデータベース/テーブル ID や Query 呼び出しを型チェックしません。

TypeScript では、結果をモジュールとしてインポートする場合は .ts の出力先を指定してください。代わりにディレクトリを渡すと、その中に appwrite.d.ts が作成されます。

appwrite types ./src/appwrite-types.ts --language ts

import { Client, TablesDB } from "appwrite";
import type { Songs } from "./appwrite-types.js";

// Read these values from appwrite.config.json and expose them through the
// application's existing configuration mechanism.
const client = new Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>");
const tablesDB = new TablesDB(client);

const page = await tablesDB.listRows<Songs>({
  databaseId: "main", // still an unchecked string
  tableId: "songs",  // still an unchecked string
});

types --strict を「完全な型安全性」と表現しないでください。これはフィールド名をターゲット言語の命名規則に変換するだけです。完全に型付けされた TypeScript のテーブル API を目指す場合は generate を使用してください。

生成されたコードは派生出力です。スキーマや命名の問題を修正するためにこれをパッチしないでください。appwrite.config.json またはジェネレーターの入力を修正し、再生成してください。テーブルやカラムを変更するたびに、リポジトリが使用しているのと同じ生成コマンドを再実行し、そのフォーマッター/型チェッカーを実行してください。リポジトリ既存の出力パスとチェックインの慣習を維持してください。

Functions とサイト

変数は appwrite.config.json ではなく <path>/.env にあります。--with-variables はそのファイルからリモートのセットを置き換えます。シークレットを同期する意図がない限りは省略してください。

# Good — ship code, leave remote vars alone
appwrite push function --function-id api --activate --force

# Bad — remote vars you did not list locally are gone
appwrite push function --function-id api --with-variables --force

# Good — deploy without switching live traffic
appwrite push function --function-id api --activate=false --force

--async はビルドが完了する前に戻ります。ローカルでは appwrite run function を使用します。

クエリと出力

--filter、--sort-asc / --sort-desc、--limit、--select、--cursor-after を推奨します。--where は非推奨です。--queries はフラグで表現できない Query JSON にのみ使用してください。

# Good
appwrite users list \
  --filter 'emailVerification=true' \
  --sort-desc '$createdAt' \
  --limit 20 \
  --json

# Bad
appwrite users list --queries '[{"method":"equal","attribute":"emailVerification","values":[true]}]'

--filter は true / false / null、数値、JSON 配列を解析します。AND で結合するにはフラグを繰り返してください。リストのページは最大 100 件です。大きな --offset よりも --cursor-after <lastId> を推奨します。

スクリプトには --json を使用します (空のフィールドは削除されます)。フィルタリングされていないペイロードには --raw を使用します。シークレットは --show-secrets を指定しない限り伏せられたままです。

設定ファイル自体について

CLI は cwd から 上方向 に appwrite.config.json（またはレガシーの appwrite.json）を探して移動します。functions/api/ からの push でもプロジェクトルートに到達します。親ディレクトリに置かれた無関係な設定ファイルに引っかかってしまうので注意してください。

大規模なプロジェクトは includes で分割します。各値は相対パスの .json 配列です。リソースをインラインと include の両方で扱うことはできません。関数とサイトの path の値は、リポジトリルートではなく include ファイルからの相対パスで解決されます。

記憶を頼りにファイルを作らないでください。init project または pull が有効なファイルを書き出します。その後で編集してください。