Packages 包City CLI

City CLI 快速开始

第一次安装和运行 city 命令时最常见的入口、连接方式和使用场景。

downcity 包会安装给 City 管理者使用的 city 命令。city 不是产品运行时 SDK。

什么时候应该先打开 city

  • 你想快速确认数据库里到底写了什么
  • 你在本地初始化 City
  • 你怀疑某个 service 没有正常建表或写数据
  • 你不想先写临时脚本，只想人工查看模型、表、schema

安装

npm i -g downcity

如果你正在当前仓库里迭代 city manage，可以直接运行：

pnpm build:cli

这个命令会先构建本地 cli/city，然后自动刷新你机器上的全局 city / town 命令。构建通过后，下一次执行 city / town 时就是当前仓库这份代码。

如果你已经装过 city / town，之后也可以直接运行：

town update

在仓库里运行时，它会优先用当前 workspace 重新 build 并刷新全局安装；不在仓库里时，则会更新到 npm 上的最新版本。

第一次运行

city

默认会先显示当前 CLI 版本，再进入交互式面板。这通常是第一次排查时最直接的入口。

如果你还没有配置任何 City，CLI 不会给你塞一个默认地址，而是会先进入欢迎页。

第一次先连接一个 City

第一次启动时，默认主路径是：

  • Connect an existing City

这一步只需要填写：

  • base_url

CLI 会先做一次公开可达性检查，然后保存这个 City 连接。

这里不会强制要求 admin_secret_key。

connect 之后会发生什么

保存成功后，这个 City 会自动成为当前工作区。接下来默认进入 user 路径：

  • 如果本地已经有这个 City 的 user session：直接进入 user workspace
  • 如果还没有 user session：直接进入 sign in

也就是说，city 现在的默认心智是：

  1. 先连接一个 City
  2. 默认走 user sign in / user workspace
  3. 只有需要管理这个 City 时，才进入 Server management

之后怎么管理 server

以后首页围绕当前 City 工作区展开：

  • Open current City
  • Switch City
  • Connect another City
  • Upgrade CLI

user workspace 里则保留高频 user 动作，例如：

  • Models
  • Balance
  • Recharge
  • My profile
  • Services

低频管理能力被收进：

  • Server management

在 Server management 里，你再按需进入：

  • Configure admin access
  • Open admin tools
  • Edit City
  • Remove City

一个最常见的上手流程

npm i -g downcity
city

这三步通常就足够你做第一轮确认：

  1. 先 connect 一个可用的 City
  2. 当前 City 连接会被保存成本地工作区
  3. 默认继续进入 user sign in / user workspace

CLI 最适合解决什么问题

场景一：人工看数据

当你的问题是：

  • “数据到底有没有写进去？”
  • “usage 事件到底有没有记录？”
  • “模型配置是不是数据库里就错了？”

CLI 往往比写脚本更快。

场景二：初始化或补录模型

city

适合：

  • 刚建好 City
  • 调整模型目录
  • 本地验证新模型配置

这些动作现在都从交互式菜单进入，而不是依赖默认 server。

场景三：手动发起 Stripe 充值

如果你的 City 启用了 payment.stripe，CLI 现在也可以直接：

  • 读取 Stripe 服务暴露的 env requirements
  • 在 Server management 里配置 admin access
  • 进入 admin tools 补齐 STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET
  • 在 Payment 里直接看到当前 server 对应的 Stripe webhook endpoint
  • 以 user 身份创建 topup
  • 继续创建 Stripe Checkout，并自动打开浏览器支付

如果你没有单独配置 STRIPE_SUCCESS_URL / STRIPE_CANCEL_URL，Stripe 服务会优先基于 DOWNCITY_CITY_BASE_URL，再回退到当前请求 origin 自动生成默认 success / cancel 页面。

Stripe webhook endpoint 本身则固定是：

  • {base_url}/v1/payment.stripe/webhook

它不适合什么

  • 不适合嵌进产品代码
  • 不适合替代管理后台逻辑
  • 不适合做长期自动化流程

这类需求更适合交给 Admin City 或你自己的后端脚本。

常用入口

这一页最常见的 CLI 入口就是：

  • city / town
  • town update
  • Connect an existing City
  • Server management
  • Sign in

常见误解

CLI 不是给终端用户用的

它是给 City 管理者、开发者、运维者用的，不是产品用户入口。

CLI 不是 Admin City 的替代品

CLI 适合“人坐在终端前的操作”；Admin City 适合“程序里长期存在的可信调用”。

CLI 不只是在看表

它也是非常好的初始化、排查和模型维护入口。

继续阅读

City CLI

用终端管理 City 的模型和数据表，适合初始化、排查和日常运维。

Models 与 Tables

用 downcity 查看 models、schema、表数据，以及它和 City 数据层的关系。

目录

什么时候应该先打开 city安装第一次运行第一次先连接一个 Cityconnect 之后会发生什么之后怎么管理 server一个最常见的上手流程CLI 最适合解决什么问题场景一：人工看数据场景二：初始化或补录模型场景三：手动发起 Stripe 充值它不适合什么常用入口常见误解CLI 不是给终端用户用的CLI 不是 Admin City 的替代品CLI 不只是在看表继续阅读