使用 Appwrite CLI 管理项目时：用…

当运行 appwrite 命令、部署或拉取 functions/sites/tables、从表结构生成应用代码、初始化或链接项目、编写 Appwrite 脚本时使用。

适用场景

解决思路

1. 运行任何 appwrite <command> 前先读 `appwrite <command> --help` 获取 flags，不要靠猜。
2. 真实项目（repo、schema、functions、deploys、CI）使用 appwrite.config.json：先 appwrite init project 一次，之后用 pull 和 push 同步；不要在每个命令上加 appwrite client --project-id，因为 config 已命名项目。
3. 一次性操作（查看用户、修补单行、临时访问远程）使用 `appwrite client`；不要为单个 API 调用搭建项目。
4. 项目式操作按示例执行：`appwrite login` → `appwrite list-projects --json` → `appwrite init project --project-id <ID>` → `appwrite pull table` → 编辑 appwrite.config.json → `appwrite push table --force`。
5. 不要用 `appwrite tablesdb create-table`、`appwrite tablesdb create-varchar-column` 等临时命令创建应由 config 管理的资源，否则下一次 clone 没有记录。
6. 一次性操作按示例执行：已登录后运行 `appwrite client --project-id <ID>`，再运行 `appwrite users get --user-id <ID> --json`；不要在无关应用目录中执行 `cd ~/some-unrelated-app && appwrite init project`。
7. 无 session 时用 `appwrite client --endpoint https://<REGION>.cloud.appwrite.io/v1 --key "$APPWRITE_API_KEY" --project-id <ID>`。
8. 用 `appwrite client --project-id` 快速链接文件夹，它会写入或更新当前目录的 appwrite.config.json（或向上查找到的文件）；不要在无关 repo 根目录运行。
9. 已在项目内但需要针对另一个项目做一次性操作时，用环境变量 `APPWRITE_PROJECT_ID` / `APPWRITE_ENDPOINT` 覆盖 config，而不修改文件。
10. 区分认证层与项目层：身份（session 或 API key）存在全局 CLI prefs，用 `appwrite login` 或 `appwrite client --key` 设置；项目存在 appwrite.config.json，用 `init project`、`pull` 或 `client --project-id` 设置。
11. `appwrite init project` 与 console 通信，需要登录 session；API key 不能列出 organizations。
12. CI 中按 checked-in config 操作：`appwrite client --key "$APPWRITE_API_KEY"` 然后 `appwrite push function --force`；不要把 key 写死在仓库，也不要提交含 secrets 的 appwrite.config.json。
13. 环境变量优先于 config：`APPWRITE_PROJECT_ID`、`APPWRITE_ENDPOINT`、`APPWRITE_ORGANIZATION_ID`；config 入库但不含 secrets，keys 放环境变量。
14. `--force` 跳过提示；Agent 和 CI 没有 TTY，需要确认的 push 不加 `--force` 会失败。先问用户，再传 `--force`。不要用它跳过本地 column 为空的 change table。
15. 用 `appwrite login --switch` 轮换已保存账户；用 `appwrite client --debug` 打印生效的 endpoint/project 且凭证打码；用 `appwrite client --reset` 登出所有。
16. Cloud：`appwrite whoami` 显示 `https://cloud.appwrite.io/v1` 是账户登录主机，保留它；项目 API 调用使用 region host，如 `https://fra.cloud.appwrite.io/v1`。
17. `init project` 和 `client --project-id` 会把 region 固定进 config；自托管时两者使用同一个 endpoint。
18. 项目工作使用 config 中的 regional endpoint（例如通过 `cat appwrite.config.json` 查看 endpoint 为 https://fra.cloud.appwrite.io/v1）；不要为“修复” whoami 而运行 `appwrite client --endpoint https://fra.cloud.appwrite.io/v1`，否则 login/session 调用会发到不该去的 region host。
19. 记住 pull/push (config) 管理的资源：settings、functions、sites、tables and columns、buckets、teams、webhooks、topics；service commands 管理但不进 config 的资源：rows、users、files、executions、messages。
20. 如果资源应在 fresh clone 后存活，就把它放进 config；编辑文件然后 push。不要用 `tablesdb create-*` 或 `functions create` 创建相同资源，那会绕过下一次 `pull`/`push` 期望的文件。
21. `databases` 已废弃；使用 `tablesdb` 和 `push table`。
22. 如果 change table 显示 remote 有值而 local 为空，说明 config 缺少这些字段：先 `appwrite pull <resource>` 再 push；不要 `--force` 穿过它，也不要仪式性 pull 全部（`pull settings` 慢）。示例：`appwrite pull settings` 然后 `appwrite push settings --force`，而不是直接 `appwrite push settings --force`。
23. `push all --all --force` 会推送每个资源；除非确实需要，否则限定范围，如 `push function --function-id api`。
24. `unique()` 适合一次性 row 或 user；需要 push 的资源在 config 中需要稳定的 `$id`，以便下一次 pull 匹配。
25. 针对 TablesDB 写应用代码前，先检查 appwrite.config.json，不要凭空发明 interfaces、database IDs、table IDs 或 column names；生成器读本地 config，不检查远程 schema，陈旧 config 会产生陈旧代码。
26. 如果远程 schema 是 source of truth，先用 `appwrite pull table` 更新 config；不要 pull 覆盖本地未推送的 schema 编辑；如果本地 config 领先，按原样生成。
27. TypeScript 优先用 `appwrite generate`；它生成完整 TablesDB wrapper，使 database 和 table 选择、create/update payloads、返回 rows、query fields、query values 都受 TypeScript 检查，比单独生成 model interfaces 更强。
28. 使用生成的 API，而不是回退到原始字符串 ID 和手写 payload 类型；例如 `import { databases, type Songs } from "./generated/appwrite/index.js";`，然后 `const songs = databases.use("main").use("Songs");` 并用 `songs.list({ queries: (query) => [query.equal("published", true), query.orderDesc("createdAt"), query.limit(20)] });`，读取 `const first: Songs | undefined = page.rows[0];`。
29. 不要猜生成示例中的字面量；读生成的类型或 config。尤其 `.use()` 对 table 取 `name`，它可能不同于 `$id`。让编译暴露拼错的 table、column 或错误 query value。生成后运行项目的 type checker。
30. `appwrite generate` 目前为 TypeScript 提供完整 wrapper；它从安装的 Appwrite package 检测 client 还是 server 输出。Server 输出读 `APPWRITE_API_KEY`；绝不要把该 key 放进生成的常量或提交。仅当检测错误时才覆盖 language、import source、module extension 或 client/server mode；读 `appwrite generate --help` 获取这些 flags。
31. 对另一种支持语言，或项目故意直接使用常规 SDK 时，用 `appwrite types <output-directory>`；支持 TypeScript (`ts`)、JavaScript (`js`)、PHP (`php`)、Kotlin (`kotlin`)、Swift (`swift`)、Java (`java`)、Dart (`dart`)、C# (`cs`)。把这些短值传给 `--language`，不要用 `typescript`、`csharp` 等不被接受的名字。
32. `appwrite types` 生成的文件会类型化 row data，但不会 type-check 原始 database/table IDs 或 `Query` 调用；例如仍需手写 `databaseId: "main"`、`tableId: "songs"`。
33. 对 TypeScript，当结果将作为模块导入时，给 `appwrite types` 传 `.ts` 目的地；传目录会在其中创建 `appwrite.d.ts`。示例：`appwrite types ./src/appwrite-types.ts --language ts`。
34. 不要描述 `types --strict` 为“full type safety”；它只把字段名转换为目标语言命名约定。目标是完全类型化 TypeScript table API 时用 `generate`。
35. 生成代码是派生输出：不要补丁它来修 schema 或命名问题；修 appwrite.config.json 或生成器输入并重新生成。
36. 每次 table 或 column 改动后，重跑仓库使用的相同生成命令，并运行其 formatter/type checker；保留仓库现有输出路径和 check-in 约定。
37. Functions 和 sites 的变量放在 `<path>/.env`，不在 appwrite.config.json；`--with-variables` 会从该文件替换远程变量集合，除非打算同步 secrets，否则省略它。
38. 部署 function 且不动远程变量时用 `appwrite push function --function-id api --activate --force`；不要用 `appwrite push function --function-id api --with-variables --force`，否则本地未列出的远程变量会消失。
39. 部署但不切换 live traffic 时用 `appwrite push function --function-id api --activate=false --force`。
40. `--async` 会在 build 完成前返回；本地运行用 `appwrite run function`。
41. 查询优先用 `--filter`、`--sort-asc` / `--sort-desc`、`--limit`、`--select`、`--cursor-after`；`--where` 已废弃；`--queries` 仅用于 flags 无法表达的 Query JSON。
42. 查询好例：`appwrite users list --filter 'emailVerification=true' --sort-desc '$createdAt' --limit 20 --json`；坏例：`appwrite users list --queries '[{"method":"equal","attribute":"emailVerification","values":[true]}]'`。
43. `--filter` 解析 `true` / `false` / `null`、数字和 JSON 数组；重复 `--filter` 表示 AND。列表页上限 100；优先 `--cursor-after <lastId>` 而非大 `--offset`。
44. 脚本用 `--json`（空字段丢弃）；需要未过滤 payload 用 `--raw`；除非 `--show-secrets`，secrets 保持 redacted。
45. CLI 从 cwd 向上查找 appwrite.config.json（或 legacy appwrite.json）；从 `functions/api/` 运行 `push` 仍会命中项目根。父目录中杂散 config 会捕获你。
46. 用 `includes` 拆分大项目，每个值是相对 `.json` 数组；资源不能既 inline 又 included；function 和 site 的 `path` 值相对 include 文件解析，不是 repo root。
47. 不要凭记忆发明配置文件；用 `init project` 或 `pull` 写出有效文件，然后再编辑。

适用边界 · 注意事项

• 项目不使用 Appwrite，或未安装/配置 Appwrite CLI、API key、项目或自托管 endpoint 时，不适用。
• 只想查询某个 appwrite 命令的可用 flags 时，直接运行 `appwrite <command> --help`，不需要套用整套项目、pull/push 和代码生成流程。
• 项目明确直接使用 Appwrite SDK，且不需要 CLI 管理 config、pull/push 或代码生成时，除一次性 client 命令外无需套用本经验。