Kyle Alas-as kyle

Joined on 2025-09-18

twenty-sdk (1.0.1)

Published 2026-03-28 15:31:37 +00:00 by kyle

Set up this registry in your project .npmrc file:

registry=

To install the package using npm, run the following command:

npm install twenty-sdk@1.0.1

or add it to the package.json file:

"twenty-sdk": "1.0.1"

For more information on the npm registry, see the documentation.

Twenty SDK

A CLI and SDK to develop, build, and publish applications that extend Twenty CRM.

Typed GraphQL clients: CoreApiClient (auto-generated per app for workspace data) and MetadataApiClient (pre-built with the SDK for workspace configuration & file uploads)
Built‑in CLI for auth, dev mode (watch & sync), uninstall, and function management
Works great with the scaffolder: create-twenty-app

Documentation

See Twenty application documentation https://docs.twenty.com/developers/extend/capabilities/apps

Prerequisites

Node.js 24+ (recommended) and Yarn 4
A Twenty workspace and an API key. Generate one at https://app.twenty.com/settings/api-webhooks

Installation

npm install twenty-sdk
# or
yarn add twenty-sdk

Usage

Usage: twenty [options] [command]

CLI for Twenty application development

Options:
  --workspace <name>   Use a specific workspace configuration (default: "default")
  -V, --version        output the version number
  -h, --help           display help for command

Commands:
  auth:login           Authenticate with Twenty
  auth:logout          Remove authentication credentials
  auth:status          Check authentication status
  auth:switch          Switch the default workspace
  auth:list            List all configured workspaces
  app:dev              Watch and sync local application changes
  app:build            Build, sync, and generate API client
  app:publish          Build and publish to npm or a Twenty server
  app:typecheck        Run TypeScript type checking on the application
  app:uninstall        Uninstall application from Twenty
  entity:add           Add a new entity to your application
  function:logs        Watch application function logs
  function:execute     Execute a logic function with a JSON payload
  help [command]       display help for command

In a scaffolded project (via create-twenty-app), use yarn twenty <command> instead of calling twenty directly. For example: yarn twenty help, yarn twenty app:dev, etc.

Global Options

--workspace <name>: Use a specific workspace configuration profile. Defaults to default. See Configuration for details.

Commands

Auth

Authenticate the CLI against your Twenty workspace.

twenty auth:login — Authenticate with Twenty.
- Options:
  - --api-key <key>: API key for authentication.
  - --api-url <url>: Twenty API URL (defaults to your current profile's value or http://localhost:3000).
- Behavior: Prompts for any missing values, persists them to the active workspace profile, and validates the credentials.
twenty auth:logout — Remove authentication credentials for the active workspace profile.
twenty auth:status — Print the current authentication status (API URL, masked API key, validity).
twenty auth:list — List all configured workspaces.
- Behavior: Displays all available workspaces with their authentication status and API URLs. Shows which workspace is the current default.
twenty auth:switch [workspace] — Switch the default workspace for authentication.
- Arguments:
  - workspace (optional): Name of the workspace to switch to. If omitted, shows an interactive selection.
- Behavior: Sets the specified workspace as the default, so subsequent commands use it without needing --workspace.

Examples:

# Login interactively (recommended)
twenty auth:login

# Provide values in flags
twenty auth:login --api-key $TWENTY_API_KEY --api-url https://api.twenty.com

# Login interactively for a specific workspace profile
twenty auth:login --workspace my-custom-workspace

# Check status
twenty auth:status

# Logout current profile
twenty auth:logout

# List all configured workspaces
twenty auth:list

# Switch default workspace interactively
twenty auth:switch

# Switch to a specific workspace
twenty auth:switch production

App

Application development commands.

twenty app:dev [appPath] — Start development mode: watch and sync local application changes.
- Behavior: Builds your application (functions and front components), computes the manifest, syncs everything to your workspace, then watches the directory for changes and re-syncs automatically. Displays an interactive UI showing build and sync status in real time. Press Ctrl+C to stop.
twenty app:build [appPath] — Build the application, sync to the server, generate the typed API client, then rebuild with the real client.
- Options:
  - --tarball: Also pack the output into a .tgz tarball.
twenty app:publish [appPath] — Build and publish the application.
- Default (no flags): builds and runs npm publish on the output directory.
- Options:
  - --server <url>: Publish to a Twenty server instead of npm (builds tarball, uploads, and installs).
  - --token <token>: Auth token for the server.
  - --tag <tag>: npm dist-tag (e.g. beta, next).
twenty app:typecheck [appPath] — Run TypeScript type checking on the application (runs tsc --noEmit). Exits with code 1 if type errors are found.
twenty app:uninstall [appPath] — Uninstall the application from the current workspace.

Entity

twenty entity:add [entityType] — Add a new entity to your application.
- Arguments:
  - entityType: one of object, field, function, front-component, role, view, navigation-menu-item, or skill. If omitted, an interactive prompt is shown.
- Options:
  - --path <path>: The path where the entity file should be created (relative to the current directory).
- Behavior:
  - object: prompts for singular/plural names and labels, then creates a *.object.ts definition file.
  - field: prompts for name, label, type, and target object, then creates a *.field.ts definition file.
  - function: prompts for a name and scaffolds a *.function.ts logic function file.
  - front-component: prompts for a name and scaffolds a *.front-component.tsx file.
  - role: prompts for a name and scaffolds a *.role.ts role definition file.
  - view: prompts for a name and target object, then creates a *.view.ts definition file.
  - navigation-menu-item: prompts for a name and scaffolds a *.navigation-menu-item.ts file.
  - skill: prompts for a name and scaffolds a *.skill.ts skill definition file.

Function

twenty function:logs [appPath] — Stream application function logs.
- Options:
  - -u, --functionUniversalIdentifier <id>: Only show logs for a specific function universal ID.
  - -n, --functionName <name>: Only show logs for a specific function name.
twenty function:execute [appPath] — Execute a logic function with a JSON payload.
- Options:
  - --preInstall: Execute the pre-install logic function defined in the application manifest (required if --postInstall, -n, and -u not provided).
  - --postInstall: Execute the post-install logic function defined in the application manifest (required if --preInstall, -n, and -u not provided).
  - -n, --functionName <name>: Name of the function to execute (required if --postInstall and -u not provided).
  - -u, --functionUniversalIdentifier <id>: Universal ID of the function to execute (required if --postInstall and -n not provided).
  - -p, --payload <payload>: JSON payload to send to the function (default: {}).

Examples:

# Start dev mode (watch, build, and sync)
twenty app:dev

# Start dev mode with a custom workspace profile
twenty app:dev --workspace my-custom-workspace

# Type check the application
twenty app:typecheck

# Add a new entity interactively
twenty entity:add

# Add a new function
twenty entity:add function

# Add a new front component
twenty entity:add front-component

# Add a new view
twenty entity:add view

# Add a new navigation menu item
twenty entity:add navigation-menu-item

# Add a new skill
twenty entity:add skill

# Uninstall the app from the workspace
twenty app:uninstall

# Watch all function logs
twenty function:logs

# Watch logs for a specific function by name
twenty function:logs -n my-function

# Execute a function by name (with empty payload)
twenty function:execute -n my-function

# Execute a function with a JSON payload
twenty function:execute -n my-function -p '{"name": "test"}'

# Execute a function by universal identifier
twenty function:execute -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -p '{"key": "value"}'

# Execute the pre-install function
twenty function:execute --preInstall

# Execute the post-install function
twenty function:execute --postInstall

Configuration

The CLI stores configuration per user in a JSON file:

Location: ~/.twenty/config.json
Structure: Profiles keyed by workspace name. The active profile is selected with --workspace <name> or by the defaultWorkspace setting.

Example configuration file:

{
  "defaultWorkspace": "prod",
  "profiles": {
    "default": {
      "apiUrl": "http://localhost:3000",
      "apiKey": "<your-api-key>"
    },
    "prod": {
      "apiUrl": "https://api.twenty.com",
      "apiKey": "<your-api-key>"
    }
  }
}

Notes:

If a profile is missing, apiUrl defaults to http://localhost:3000 until set.
twenty auth:login writes the apiUrl and apiKey for the active workspace profile.
twenty auth:login --workspace custom-workspace writes the apiUrl and apiKey for a custom custom-workspace profile.
twenty auth:switch sets the defaultWorkspace field, which is used when --workspace is not specified.
twenty auth:list shows all configured workspaces and their authentication status.

Troubleshooting

Auth errors: run twenty auth:login again and ensure the API key has the required permissions.
Typings out of date: restart twenty app:dev to refresh the client and types.
Not seeing changes in dev: make sure dev mode is running (twenty app:dev).

Contributing

Development Setup

To contribute to the twenty-sdk package, clone the repository and install dependencies:

git clone https://github.com/twentyhq/twenty.git
cd twenty
yarn install

Development Mode

Run the SDK build in watch mode to automatically rebuild on file changes:

npx nx run twenty-sdk:dev

This will watch for changes and rebuild the dist folder automatically.

Production Build

Build the SDK for production:

npx nx run twenty-sdk:build

Running the CLI Locally

After building, you can run the CLI directly:

npx nx run twenty-sdk:start -- <command>
# Example: npx nx run twenty-sdk:start -- auth:status

Or run the built CLI directly:

node packages/twenty-sdk/dist/cli.cjs <command>

Resources

See our GitHub
Join our Discord

Dependencies

ID	Version
@chakra-ui/react	^3.33.0
@emotion/react	^11.14.0
@genql/cli	^3.0.3
@genql/runtime	^2.10.0
@quilted/threads	^4.0.1
@remote-dom/core	^1.10.1
@remote-dom/react	^1.2.2
@sniptt/guards	^0.2.0
axios	^1.13.5
chalk	^5.3.0
chokidar	^4.0.0
commander	^12.0.0
dotenv	^16.4.0
esbuild	^0.25.0
graphql	^16.8.1
graphql-sse	^2.5.4
ink	^5.1.1
inquirer	^10.0.0
jsonc-parser	^3.2.0
preact	^10.28.3
react	^18.2.0
react-dom	^18.2.0
tinyglobby	^0.2.15
typescript	^5.9.2
uuid	^13.0.0
vite	^7.0.0
vite-tsconfig-paths	^4.2.1
zod	^4.1.11

Development Dependencies

ID	Version
@emotion/styled	^11.14.0
@mui/material	^7.3.8
@prettier/sync	^0.5.2
@storybook/addon-vitest	^10.2.13
@storybook/react-vite	^10.2.13
@types/inquirer	^9.0.0
@types/node	^24.0.0
@types/react	18.2.66
@types/react-dom	18.2.22
@vitest/browser-playwright	^4.0.18
playwright	^1.56.1
storybook	^10.2.13
ts-morph	^25.0.0
tsx	^4.7.0
twenty-shared	workspace:*
twenty-ui	workspace:*
vite-plugin-dts	^4.5.4
wait-on	^7.2.0

twenty cli sdk crm application development

Details

npm

2026-03-28 15:31:37 +00:00

AGPL-3.0

latest

2.3 MiB

Assets (1)

twenty-sdk-1.0.1.tgz 2.3 MiB

Versions (3) View all

1.0.1

2026-03-28

0.7.0

2026-03-28

1.0.0

2026-03-28

twenty-sdk (1.0.1)

Installation

About this package

Twenty SDK

Documentation

Prerequisites

Installation

Usage

Global Options

Commands

Auth

App

Entity

Function

Configuration

Troubleshooting

Contributing

Development Setup

Development Mode

Production Build

Running the CLI Locally

Resources

Dependencies

Keywords