> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upshiftcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Create your first Upshift app in minutes.

## Prerequisites

* **Node.js 24.5+** — [Download](https://nodejs.org/)
* **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`
* **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Upshift server. Skip if you already have Upshift running elsewhere.

Building a Upshift app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.

| Phase | What you do | Tool | Result |
| - | - | - | - |
| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |
| **2. Run a server** | Start a Upshift server to sync into | Docker + `yarn twenty docker:start` | A running Upshift instance |
| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |

***

## Phase 1 — Scaffold your project

Create a new app from the template:

```bash filename="Terminal" theme={null}
npx create-twenty-app@latest my-upshift-app
```

The scaffolder is non-interactive: the directory name becomes the app name. Pass `--display-name` and `--description` to customize the generated metadata (you can also edit it later in `src/constants/universal-identifiers.ts`). This generates a TypeScript project in `my-upshift-app/` with a starter `application-config.ts`, a default role, CI/CD workflows, and an integration test.

**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.

***

## Phase 2 — Run a local Upshift server

Your app needs a Upshift server to sync into. The server is a full Upshift instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.

The scaffolder starts one for you: with Docker running, it pulls the `twentycrm/twenty-app-dev` image, starts it on port `2020`, and authenticates the CLI against the pre-seeded demo workspace (`tim@apple.dev`) — no sign-in required.

To connect to an existing Upshift server instead, pass `--url <your-server-url>`. Remote servers authenticate with OAuth: a browser opens so you can sign in and click **Authorize**, which gives the CLI access to your workspace. (You can also opt into OAuth locally with `--authentication-method oauth` — sign in with `tim@apple.dev` / `tim@apple.dev`.)

![Upshift login screen](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/login.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=7c91469ebb18f56d243525142af05a84)

![Upshift CLI authorization screen](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/authorize.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=e087f612ddfeacf720d35bd977fbc1fd)

Your terminal will confirm everything is set up.

![App scaffolded successfully](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/scaffolded.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=2c91a95d78cf925112b073e9f273faa6)

**After this phase:** you have a running Upshift server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.

> [!NOTE]
>
> If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty docker:start` — no need to re-scaffold.

***

## Phase 3 — Sync your changes

This is the inner loop you'll spend most of your time in.

```bash filename="Terminal" theme={null}
cd my-upshift-app
yarn twenty dev
```

This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a few seconds the server reflects the change. You'll see a live status panel in your terminal.

For more detailed output (build logs, sync requests, error traces), add `--verbose`.

![Dev mode terminal output](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/dev.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=2b10e8c1124a041db252464abeee5129)

Open [http://localhost:2020/settings/developers#apps](http://localhost:2020/settings/developers#apps). You should see your app under **My apps**.

![Your Apps list showing My upshift app](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/app-in-ui-1.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=de21ce3a2e0b8ae8454049a60cc390c5)

Click **My upshift app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.

![Application registration details](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/app-in-ui-2.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=70a663c116c9af918bc0b26a8a7ca998)

Click **View installed app** to see the workspace install. The **About** tab shows version and management options.

![Installed app](https://mintcdn.com/exceev-group/1cFKDdENVawzNm26/images/docs/developers/extends/apps/app-in-ui-3.png?fit=max\&auto=format\&n=1cFKDdENVawzNm26\&q=85\&s=4ee5b459d41a2cf2210ff443f2a19b74)

**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.

### One-shot sync for CI and scripts

Use `plan` and `apply` to run the same pipeline once, without a watcher:

```bash filename="Terminal" theme={null}
yarn twenty plan   # preview the metadata changes without applying them
yarn twenty apply  # show the plan, then apply it
```

| Command | Behavior | When to use |
| - | - | - |
| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
| `yarn twenty apply` | Single build + sync, exits `0` on success, `1` on failure. Asks for confirmation on destructive changes (pass `--force` to skip). | CI, pre-commit hooks, AI agents, scripted workflows. |
| `yarn twenty plan` | Builds and prints the metadata changes **without applying them**. | Inspecting what a sync would change before committing to it. |

All modes need an authenticated remote. See [Syncing & recovery](https://docs.upshiftcloud.com/en/developers/extend/apps/operations/sync-and-recovery.md#previewing-changes-plan) for more on `plan`.

> [!NOTE]
>
> All three modes require your workspace to own the app's registration. The sync is refused when the `universalIdentifier` from your app config is registered to another workspace, or to no workspace yet — apps imported from the marketplace catalog start unowned and have to be claimed first. See [Registration ownership](https://docs.upshiftcloud.com/en/developers/extend/apps/operations/publishing.md#registration-ownership).

> [!NOTE]
>
> `yarn twenty dev --once` and `yarn twenty dev --once --dry-run` are deprecated aliases for `yarn twenty apply` and `yarn twenty plan`.

### Dev mode options

| Flag | Description |
| - | - |
| `--force` | Apply destructive changes (deletes) without confirmation. |
| `--no-delete` | Keep entities that are missing from your source instead of deleting them. Also accepted by `plan` and `apply`. |
| `--debounceMs <ms>` | Set the file-change debounce delay in milliseconds (default: `1000`). |
| `--verbose` / `--debug` | Show detailed build logs, sync requests, and error traces. |

## What you can build

Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:

| Entity | What it does |
| - | - |
| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |
| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
| **Front components** | React components that render inside Upshift's UI (side panel, widgets, command menu) |
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
| **Views & Navigation** | Pre-configured list views and sidebar menu items |
| **Page layouts** | Custom record detail pages with tabs and widgets |

Full reference: [Concepts](https://docs.upshiftcloud.com/en/developers/extend/apps/getting-started/concepts.md).

## Next steps

> **[Config](https://docs.upshiftcloud.com/en/developers/extend/apps/config/overview.md)**
>
> Application identity, default role, install and uninstall hooks, public assets.

> **[Data](https://docs.upshiftcloud.com/en/developers/extend/apps/data/overview.md)**
>
> Objects, fields, and bidirectional relations.

> **[Logic](https://docs.upshiftcloud.com/en/developers/extend/apps/logic/overview.md)**
>
> Logic functions, skills, agents, and OAuth connections.

> **[Layout](https://docs.upshiftcloud.com/en/developers/extend/apps/layout/overview.md)**
>
> Views, navigation, page layouts, front components.

> **[Operations](https://docs.upshiftcloud.com/en/developers/extend/apps/operations/overview.md)**
>
> CLI, testing, remotes, CI, and publishing your app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.