---
name: manage-app
description: Use when the user wants to manage or troubleshoot tooling, remotes, sync, build, deploy, logs, CI/CD, or operational workflows for an existing Twenty app.
title: manage-app
canonical_url: https://skilld.dev/gh/twentyhq/twenty/manage-app
last_updated: 2026-11-13T12:01:00.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/twentyhq/twenty/manage-app/agents/openai.yaml).
>
> If the user asked to install this Skill, run `npx skilld install twentyhq/twenty/manage-app`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/manage-app`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/twentyhq/twenty/manage-app) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/manage-app`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/manage-app --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/manage-app --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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:

```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
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
twenty local 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.

# 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:

```bash
# 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:

```bash
# 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:

```bash
twenty app apply
```

Do 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:

```bash
sed -n '1,220p' package.json
sed -n '1,220p' src/application-config.ts
twenty remote list
twenty app apply --json
```

For remote or authentication issues:

- Check that the active remote is the intended workspace or server.
- Re-run `twenty auth login --url http://localhost:2020` for 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_REQUIRED` means a proxy in front of the server sent the request to its sign-in page; configure proxy headers as described under remotes. `PROXY_HEADERS_FAILED` means the proxy header command failed; have the user run it to sign in to the proxy again.

For sync issues:

- Prefer `twenty app apply --json` 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 `twenty app build` before `twenty app publish --private` or `twenty app publish`.
- Check `package.json` version 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 logs` to 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_URL` points to a reachable server from the runner.
- Confirm `TWENTY_DEPLOY_API_KEY` is 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:

```bash
twenty app build
```

Publish an app to npm, or publish privately to a configured Twenty server registry:

```bash
twenty app publish
twenty app publish --private --remote production
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 `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:

```bash
twenty app logs
twenty app logs --name <function-name>
```

Run a logic function manually when testing behavior without its trigger:

```bash
twenty app exec --name <function-name>
twenty app exec --name <function-name> --payload '{"key":"value"}'
```

Uninstall only after confirmation:

```bash
twenty app uninstall
twenty app uninstall --yes
```

# CI/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_URL`
- `TWENTY_DEPLOY_API_KEY`

Do not put API keys in source files. Use the repository or CI secret store.
