Back to Details

manage-app

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When To Use

何时使用

Pick this skill when the user wants to operate, troubleshoot, or ship an existing Twenty app — anything between "I have an app" and "it runs in production". Representative triggers:
  • "sync my app changes to the server"
  • "deploy my Twenty app to production"
  • "check the logs for my logic function"
  • "switch to a different Twenty remote / instance"
  • "add a new remote for staging"
  • "set up CI/CD for my Twenty app"
  • "troubleshoot a failed deploy / sync / build"
  • "uninstall my app from production"
  • "run tests for my Twenty app"
  • "run my logic function manually for testing"
Do not use this skill to scaffold (use 
create-app
), to change app entities or code (use 
develop-app
), to prepare marketplace assets (use 
publish-app
), or to query workspace records (use 
use-twenty-mcp
).
当用户希望操作、排查或发布现有 Twenty app 时，请选择此 skill——无论是“我已经有 app”还是“它已在生产环境中运行”。典型触发场景包括：
  • “将我的 app 更改同步到服务器”
  • “将我的 Twenty app 部署到生产环境”
  • “查看我的 logic function 日志”
  • “切换到其他 Twenty remote / instance”
  • “为 staging 添加新的 remote”
  • “为 Twenty app 设置 CI/CD”
  • “排查失败的 deploy / sync / build”
  • “从生产环境卸载我的 app”
  • “为我的 Twenty app 运行测试”
  • “手动运行 logic function 进行测试”
不要使用此 skill 来 scaffold（使用 
create-app
）、更改 app entities 或代码（使用 
develop-app
）、准备 marketplace assets（使用 
publish-app
），或查询 workspace records（使用 
use-twenty-mcp
）。

Boundaries

边界

For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read 
../../references/concepts/how-apps-work.md
. Cross-skill operating rules that apply to every Twenty app task are in 
../../references/concepts/operating-rules.md
; they are authoritative and not restated per skill.
Do not scaffold a new app here. Use 
$create-app
when the app does not exist.
Do not add or modify app entities here. Use 
$develop-app
for objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, connection providers, front component registration, and settings menu items.
Do not prepare marketplace README, screenshots, logos, or npm listing copy here. Use 
$publish-app
for public listing work.
Do not retrieve CRM records here. Use 
$use-twenty-mcp
for workspace data retrieval.
有关 Twenty apps 工作原理的背景信息——SDK packages、remotes、sync lifecycle 和 rendering model——请阅读 
../../references/concepts/how-apps-work.md
。适用于所有 Twenty app 任务的跨 skill 操作规则位于 
../../references/concepts/operating-rules.md
；这些规则具有权威性，不会在每个 skill 中重复说明。
不要在此处 scaffold 新 app。当 app 尚不存在时，使用 
$create-app
。
不要在此处添加或修改 app entities。使用 
$develop-app
处理 objects、fields、logic functions、roles、views、navigation、page layouts、skills、agents、connection providers、front component registration 和 settings menu items。
不要在此处准备 marketplace README、screenshots、logos 或 npm listing copy。使用 
$publish-app
完成公开列表相关工作。
不要在此处检索 CRM records。使用 
$use-twenty-mcp
获取 workspace 数据。

Operating Rules

操作规则

First confirm the current directory is a Twenty app:
bash
test -f package.json
test -f src/application-config.ts
Inspect current app and scripts before running operational commands:
bash
sed -n '1,220p' package.json
yarn twenty remote:list
Treat deploys, uninstalls, production remote changes, and production syncs as externally visible actions. Ask for explicit confirmation before running them when the target is production or user data could be affected.
For command details, remotes, validation command semantics, sync modes, troubleshooting, build, deploy, logs, exec, and CI/CD, read 
../../references/manage-app/cli-and-sync.md
.
If the user asks to run tests, also read 
../../references/develop-app/tests.md
before running any test command. Full test suites include integration tests that install and uninstall the app on their target server, so start or verify the isolated test instance and run:
bash
yarn twenty docker:start --test
TWENTY_API_URL=http://localhost:2021 yarn test
Do not run integration tests against the dev instance on 
http://localhost:2020
unless the user explicitly asks for that target. If the user asks for unit tests only, use the package's unit-test script and no 
TWENTY_API_URL
override is needed.
首先确认当前目录是一个 Twenty app：
bash
test -f package.json
test -f src/application-config.ts
在运行运维命令之前，检查当前 app 和 scripts：
bash
sed -n '1,220p' package.json
yarn twenty remote:list
将 deploy、uninstall、production remote 变更和 production sync 视为会对外产生影响的操作。当目标为生产环境或可能影响用户数据时，运行前必须获得明确确认。
有关命令详情、remotes、validation command semantics、sync modes、troubleshooting、build、deploy、logs、exec 和 CI/CD，请阅读 
../../references/manage-app/cli-and-sync.md
。
如果用户要求运行测试，还必须在运行任何测试命令前阅读 
../../references/develop-app/tests.md
。完整测试套件包括 integration tests，会在目标 server 上 install 和 uninstall app，因此应先启动或确认隔离的 test instance，然后运行：
bash
yarn twenty docker:start --test
TWENTY_API_URL=http://localhost:2021 yarn test
除非用户明确要求针对该目标运行，否则不要对 
http://localhost:2020
上的 dev instance 运行 integration tests。如果用户只要求 unit tests，请使用 package 的 unit-test script，且无需覆盖 
TWENTY_API_URL
。

Remotes

Remotes

A remote is a Twenty server that the app can sync or deploy to. Credentials are stored locally in 
~/.twenty/config.json
.
Common commands:
bash
undefined
remote 是 app 可以向其 sync 或 deploy 的 Twenty server。凭据存储在本地 
~/.twenty/config.json
中。
常用命令：
bash
undefined

Add a remote interactively.

Add a remote interactively.

yarn twenty remote:add
yarn twenty remote:add

Connect to a local Twenty server.

Connect to a local Twenty server.

yarn twenty remote:add --local
yarn twenty remote:add --local

Add a remote non-interactively.

Add a remote non-interactively.

yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production
yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production

List configured remotes.

List configured remotes.

yarn twenty remote:list
yarn twenty remote:list

Switch the active remote.

Switch the active remote.

yarn twenty remote:use <name>

When the user says "prod", "production", or "workspace de prod", identify the target remote before syncing or deploying. If it is missing, add it with `--as production` or the user-provided name.
yarn twenty remote:use <name>

当用户提到“prod”、“production”或“workspace de prod”时，在 sync 或 deploy 前确定目标 remote。如果尚未配置，则使用 `--as production` 或用户提供的名称添加该 remote。

Development Sync

开发同步

Always use bounded apply to synchronize app changes with the active remote:
bash
yarn twenty apply
Do not use bare 
yarn twenty dev
(watch mode). Run 
yarn twenty apply
each time changes need to be synced.
Bounded apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
始终使用 bounded apply 将 app 更改同步到 active remote：
bash
yarn twenty apply
不要直接使用 
yarn twenty dev
（watch mode）。每次需要同步更改时，都运行 
yarn twenty apply
。
bounded apply 需要已通过身份验证的 remote。如果身份验证失败，请重新添加或切换 remote 后再重试。

Troubleshooting

故障排查

Start by identifying which layer is failing:
  • Remote/authentication.
  • Dev sync or bounded apply.
  • Build/package generation.
  • Deploy/upload/install.
  • Runtime function execution.
  • CI/CD environment or secrets.
Collect the minimum useful context before changing configuration:
bash
sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
yarn twenty remote:list
yarn twenty apply --verbose
For remote or authentication issues:
  • Check that the active remote is the intended workspace or server.
  • Re-run 
    yarn twenty remote:add --local
    for local app-dev servers.
  • Re-run 
    yarn twenty remote:add --url <url> --as <name>
    for remote servers.
  • Avoid overwriting a production remote until the target URL is confirmed.
For sync issues:
  • Prefer 
    yarn twenty apply --verbose
    to get a bounded failure.
  • Check generated type or schema errors before editing app entities.
  • If the app depends on a changed data model, use 
    $develop-app
    to fix the entity definitions.
For build or deploy issues:
  • Run 
    yarn twenty dev:build
    before 
    yarn twenty app:publish --private
    or 
    yarn twenty app:publish
    .
  • Check 
    package.json
    version when updating an already deployed app.
  • Confirm the target with 
    yarn twenty app:publish --private --remote <name>
    instead of relying on the active remote when production is involved.
For runtime behavior:
  • Use 
    yarn twenty dev:function:logs
    to inspect function execution logs.
  • Use 
    yarn twenty dev:function:exec -n <function-name> -p '<json>'
    to reproduce a logic function with a controlled payload.
For CI/CD failures:
  • Check 
    .github/workflows/
    .
  • Confirm 
    TWENTY_DEPLOY_URL
    points to a reachable server from the runner.
  • Confirm 
    TWENTY_DEPLOY_API_KEY
    is configured as a secret, not committed in source.
首先确定故障所在的层：
  • Remote/身份验证。
  • Dev sync 或 bounded apply。
  • Build/package generation。
  • Deploy/upload/install。
  • Runtime function execution。
  • CI/CD environment 或 secrets。
在修改配置前，收集最少但有用的上下文：
bash
sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
yarn twenty remote:list
yarn twenty apply --verbose
对于 remote 或身份验证问题：
  • 确认 active remote 是预期的 workspace 或 server。
  • 对本地 app-dev server，重新运行 
    yarn twenty remote:add --local
    。
  • 对远程 server，重新运行 
    yarn twenty remote:add --url <url> --as <name>
    。
  • 在确认目标 URL 前，不要覆盖 production remote。
对于 sync 问题：
  • 优先使用 
    yarn twenty apply --verbose
    获取范围明确的失败信息。
  • 在编辑 app entities 前，检查生成的 type 或 schema 错误。
  • 如果 app 依赖已更改的 data model，使用 
    $develop-app
    修复 entity definitions。
对于 build 或 deploy 问题：
  • 运行 
    yarn twenty dev:build
    ，然后再运行 
    yarn twenty app:publish --private
    或 
    yarn twenty app:publish
    。
  • 更新已部署的 app 时，检查 
    package.json
    中的 version。
  • 涉及 production 时，使用 
    yarn twenty app:publish --private --remote <name>
    确认目标，不要依赖 active remote。
对于运行时行为：
  • 使用 
    yarn twenty dev:function:logs
    查看 function execution logs。
  • 使用 
    yarn twenty dev:function:exec -n <function-name> -p '<json>'
    以受控 payload 复现 logic function。
对于 CI/CD 故障：
  • 检查 
    .github/workflows/
    。
  • 确认 
    TWENTY_DEPLOY_URL
    指向 runner 可以访问的 server。
  • 确认 
    TWENTY_DEPLOY_API_KEY
    已配置为 secret，而不是提交到 source 中。

Build And Deploy

构建与部署

Build before deploy when the user asks for release readiness or when debugging packaging issues:
bash
yarn twenty dev:build
Publish an app to npm, or publish privately to a configured Twenty server registry:
bash
yarn twenty app:publish
yarn twenty app:publish --private --remote production
yarn twenty app:install --remote production
Before deploying an update, check that 
package.json
has a strictly higher semver 
version
than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with 
yarn twenty app:install
when the target workspace should use it.
Use 
$publish-app
instead when the user wants npm marketplace publishing, listing copy, screenshots, or public app store metadata.
在用户要求确认发布就绪状态或排查打包问题时，部署前先进行构建：
bash
yarn twenty dev:build
将 app 发布到 npm，或以私有方式发布到已配置的 Twenty server registry：
bash
yarn twenty app:publish
yarn twenty app:publish --private --remote production
yarn twenty app:install --remote production
部署更新前，检查 
package.json
中的 
version
是否具有严格高于当前已部署版本的 semver。重新部署相同版本会被拒绝。私有发布后，当目标 workspace 应使用该版本时，运行 
yarn twenty app:install
安装已部署版本。
当用户希望发布到 npm marketplace、准备 listing copy、screenshots 或 public app store metadata 时，改用 
$publish-app
。

Logs, Exec, And Cleanup

日志、执行与清理

Use function logs when debugging runtime behavior on the connected server:
bash
yarn twenty dev:function:logs
yarn twenty dev:function:logs -n <function-name>
Run a logic function manually when testing behavior without its trigger:
bash
yarn twenty dev:function:exec -n <function-name>
yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'
Uninstall only after confirmation:
bash
yarn twenty app:uninstall
yarn twenty app:uninstall --yes
在已连接的 server 上调试运行时行为时，使用 function logs：
bash
yarn twenty dev:function:logs
yarn twenty dev:function:logs -n <function-name>
在没有触发器的情况下测试行为时，手动运行 logic function：
bash
yarn twenty dev:function:exec -n <function-name>
yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'
仅在获得确认后执行 uninstall：
bash
yarn twenty app:uninstall
yarn twenty app:uninstall --yes

CI/CD

CI/CD

Apps generated with 
create-twenty-app
can use GitHub Actions for CI and CD. For deployment automation, check the app's 
.github/workflows/
files and configure:
  • TWENTY_DEPLOY_URL
  • TWENTY_DEPLOY_API_KEY
Do not put API keys in source files. Use the repository or CI secret store.
由 
create-twenty-app
生成的 app 可以使用 GitHub Actions 进行 CI 和 CD。对于 deployment automation，请检查 app 的 
.github/workflows/
文件并配置：
  • TWENTY_DEPLOY_URL
  • TWENTY_DEPLOY_API_KEY
不要将 API keys 放入 source files。请使用 repository 或 CI secret store。