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).
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.
Operating Rules
First confirm the current directory is a Twenty app:
test -f package.json
test -f src/application-config.tsInspect current app and scripts before running operational commands:
sed -n '1,220p' package.json
twenty remote listTreat 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:
twenty local start --test
TWENTY_API_URL=http://localhost:2021 yarn testDo 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.
Remotes
A remote is a Twenty server that the app can sync or deploy to. Credentials are managed by the standalone CLI. Use twenty auth login and twenty remote list.
Common commands:
# Add a remote interactively.
twenty auth login
# Connect to a local Twenty server.
twenty auth login --url http://localhost:2020
# Add a remote non-interactively.
printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://your-twenty-server.com --name production
# List configured remotes.
twenty remote list
# Switch the active remote.
twenty remote use <name>If the server sits behind an authenticating proxy (Cloudflare Access, Google IAP, Pomerium, oauth2-proxy), commands fail with PROXY_AUTH_REQUIRED. Ask the user how the proxy authenticates. Never invent or echo credentials. Then save its headers on the remote:
# Short-lived per-user token: a command that prints "Name: value" lines, rerun when the proxy rejects it.
twenty auth login --url <url> --proxy-header-command 'echo "cf-access-token: $(cloudflared access token -app=<url>)"'
# Fixed service-token headers, repeatable.
twenty auth login --url <url> --proxy-header "CF-Access-Client-Id: <id>" --proxy-header "CF-Access-Client-Secret: <secret>"In CI, set TWENTY_PROXY_HEADERS (one Name: value per line) or TWENTY_PROXY_HEADER_COMMAND instead. Proxy headers are only sent to the remote's API URL and cannot replace Authorization.
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.
Development Sync
Always use bounded apply to synchronize app changes with the active remote:
twenty app applyDo not use bare twenty app dev (watch mode). Run twenty app 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.
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:
sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
twenty remote list
twenty app apply --jsonFor remote or authentication issues:
- Check that the active remote is the intended workspace or server.
- Re-run
twenty auth login --url http://localhost:2020for local app-dev servers. - Re-run
twenty auth login --url <url> --name <name>for remote servers. - Avoid overwriting a production remote until the target URL is confirmed.
PROXY_AUTH_REQUIREDmeans a proxy in front of the server sent the request to its sign-in page; configure proxy headers as described under remotes.PROXY_HEADERS_FAILEDmeans the proxy header command failed; have the user run it to sign in to the proxy again.
For sync issues:
- Prefer
twenty app apply --jsonto 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-appto fix the entity definitions.
For build or deploy issues:
- Run
twenty app buildbeforetwenty app publish --privateortwenty app publish. - Check
package.jsonversion when updating an already deployed app. - Confirm the target with
twenty app publish --private --remote <name>instead of relying on the active remote when production is involved.
For runtime behavior:
- Use
twenty app logsto inspect function execution logs. - Use
twenty app exec --name <function-name> --payload '<json>'to reproduce a logic function with a controlled payload.
For CI/CD failures:
- Check
.github/workflows/. - Confirm
TWENTY_DEPLOY_URLpoints to a reachable server from the runner. - Confirm
TWENTY_DEPLOY_API_KEYis configured as a secret, not committed in source.
Build And Deploy
Build before deploy when the user asks for release readiness or when debugging packaging issues:
twenty app buildPublish an app to npm, or publish privately to a configured Twenty server registry:
twenty app publish
twenty app publish --private --remote production
twenty app install --remote productionBefore 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 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.
Logs, Exec, And Cleanup
Use function logs when debugging runtime behavior on the connected server:
twenty app logs
twenty app logs --name <function-name>Run a logic function manually when testing behavior without its trigger:
twenty app exec --name <function-name>
twenty app exec --name <function-name> --payload '{"key":"value"}'Uninstall only after confirmation:
twenty app uninstall
twenty app uninstall --yesCI/CD
Apps generated with twenty app init can use GitHub Actions for CI and CD. For deployment automation, check the app's .github/workflows/ files and configure:
TWENTY_DEPLOY_URLTWENTY_DEPLOY_API_KEY
Do not put API keys in source files. Use the repository or CI secret store.