Proposal: Adopt twenty-cli as official CLI tool

[salmonumbrella]

Hi @charlesBochet @FelixMalfait 👋

I built a CLI for Twenty CRM that I'd like to donate to the project: https://github.com/salmonumbrella/twenty-cli

Why a CLI matters

CLIs are the primary interface for AI agents and automation tools. As LLM-powered agents become standard for business workflows, having an official CLI means:

• AI agents (Claude, GPT, Cursor, etc.) can interact with Twenty natively
• CI/CD pipelines can automate CRM operations
• Power users get scriptable access to their data
• Developers can build integrations faster

What it does

• 100% API coverage - people, companies, opportunities, tasks, notes, webhooks, custom objects
• Multiple profiles - manage multiple Twenty workspaces
• Secure credential storage - system keychain on macOS/Linux/Windows
• Bulk import/export - CSV and JSON support
• Rate limit handling - automatic retry with exponential backoff
• Environment variable support - headless/CI friendly

Installation

Already available via Homebrew:

brew install salmonumbrella/tap/twenty-cli

Proposal

I'd like Twenty to take ownership of this CLI. Benefits:

1. Discoverability - users find it in the official repo
2. Community contributions - more maintainers, faster iteration
3. Consistency - stays in sync with API changes
4. Trust - official tooling users can rely on

I'm happy to:

• Transfer the repo or submit as a PR to packages/twenty-cli
• Continue maintaining it as a contributor
• Help with documentation and onboarding

Let me know if you're interested!

cc: @Weiko @bosiraphael @thomtrp @lucasbordeau

[charlesBochet]

@salmonumbrella Love the enthousiasm! We are already developing: https://www.npmjs.com/package/twenty-sdk which seems to be aiming for the same goal.

It's still very experimental and I'm not sure it's ready for external contribution, the vision is still a bit blurry. @martmull fyi if you want to try collaborating with @salmonumbrella

[salmonumbrella]

@charlesBochet you're so fast!

I started by forking Twenty SDK, and I wrapped your entire REST and GraphQL APIs. My CLI is for controlling Twenty. I was inspired by clawdbot, which wraps APIs as CLI tools specifically for AI agent consumption.

• CLI + SDK can coexist: The SDK is great for programmatic integrations; a CLI shines for shell scripting, AI agents, and quick admin tasks
• Homebrew distribution would lower the barrier for users to get started (brew install twenty-cli)

[charlesBochet]

@salmonumbrella one of our learnings from the winter iterations is that SDK and CLI should be live in the same npm package, but I'll leave it to @martmull to give you more details

[martmull]

Hey @salmonumbrella — thank you for this contribution, I took some time to review it and I think it’s genuinely interesting. A CLI-wrapped API like this can be very valuable, especially for UI agents and automation use cases.

I particularly like the authentication profile concept. We already have something similar with the --workspace flag, but we don’t currently support something like twenty auth switch, and that’s definitely a feature we’d be happy to add.

Looking at the bigger picture, I think it would make a lot of sense to integrate this work directly into twenty-sdk, rather than maintaining it as a separate package. We’re currently building a CLI layer there, and your work would fit very naturally as the foundation of that effort.

One architectural point we’d like to align on:

• Rather than having dedicated commands for each default object (person, company, etc.), we’d prefer a more generic approach such as twenty api <object> <operation> <options> that works for both default and custom objects.

• For metadata, something like twenty api-metadata <metadata> <operation> <options> would keep things consistent and flexible.

One question as well: what motivated the choice of Go for this tool? Since the rest of the Twenty codebase (including twenty-sdk) is written in TypeScript, integrating and maintaining this long-term would be significantly simpler if it lived in the same ecosystem.

Would you be open to collaborating on integrating this work into twenty-sdk, potentially adapting it to TypeScript? I think this could be a great addition to the project, and your experience building this CLI would be extremely valuable.

Looking forward to your thoughts!

[salmonumbrella]

Hey @martmull — thanks for the thoughtful review and for the kind words. Super aligned that a CLI‑wrapped API is valuable for agents/automation, and I’m glad the auth profiles resonated.

On architecture: the current CLI already has a generic path (records works for default + custom objects; objects/fields cover metadata; plus raw rest/graphql). The dedicated commands are mostly sugar. If you’d rather consolidate to twenty api <object> <operation> and twenty api-metadata <metadata> <operation>, I’m happy to refactor/alias the surface to that model.

On Go vs TS: I chose Go mainly for distribution and UX — single static binary, fast cold start, no Node runtime/toolchain, easy Homebrew install. That’s why so many popular CLIs (gh, kubectl, flyctl) lean Go. I totally get the ecosystem point, though. If the team’s priority is “lives in twenty-sdk = TS only,” I’m open to helping port the command layer and keeping the API core aligned (or even generating both from the same schema).

Also, Vercel’s agent-browser is a Rust CLI (with a Node.js fallback):
https://github.com/vercel-labs/agent-browser

Happy to collaborate either way!

[martmull]

@salmonumbrella great to hear. Ok i understand better the go choice. Nevertheless I think we will stuck on typescript for an integration in twenty-sdk. Your README documents your commands very well so I think it can be easy to do for an agent like Claude to do it. What do you think?

I understand the sugar for standard object commands, but in the case of an integration in the twenty-sdk command, I think it would be more simple to isolate the cli-wrapped api behind a dedicate command name like api. For that reason I would stick to twenty api <object> <operation> and twenty api-metadata <metadata> <operation>

I have created a ticket for the twenty auth switch <profile> and twenty auth list which can be separatedly -> twentyhq/twenty#17102

[salmonumbrella]

I disagree on the TypeScript because I think it’s harder to distribute the binary. Can you guys please have one final think after looking at famous CLIs, and once you decide then I’ll start building in your direction 🙏

[charlesBochet]

I would say that there are also several examples of CLIs that are written on TS and that are super successful:

• https://github.com/vercel/next.js/tree/canary/packages/create-next-app
• https://github.com/expo/expo/tree/main/packages/create-expo/src

Stepping back on how we think Twenty customization:

1. (UI) using the Settings UI: this will update a pre-installed custom app => out of scope for discussion
2. (UI) using in-product AI agents to customize your workspace: very similar to Settings UI => out of scope for discussion
3. (UI) installing from the marketplace => out of scope for discussion
4. creating you own custom app => you'll have to be in ts ecosystem to create your serverless functions anyway => npx is the recommended way
5. using an AI "IDE" or "prompt" that would perform cli API calls or directly make the API calls your self in order to customize your workspace => I think it's what you have in mind. I think in this case, we would still push you toward creating your own custom app (4.) as you will benefit from a way better devXP: code is versioned, code can be deployed through CI/CD, staging environment, code can be published to the marketplace, AI is better to produce code than making API calls. In case you really want to only perform API calls through CLI, having to install npx and use npx to run the script is quite straight forward and well supported on all OS

So I think we should prioritize keeping the sdk in the same language so contributors can easily contribute to it too

[salmonumbrella]

Hey @charlesBochet @martmull — I've ported the CLI to TypeScript! 🎉

Repository: https://github.com/salmonumbrella/twenty-cli

The CLI now follows the architecture you outlined:

• twenty api <object> <operation> — generic records API for default and custom objects
• twenty api-metadata <type> <operation> — metadata operations for objects and fields
• twenty auth login/status/list/switch/logout — workspace profile management
• Plus: twenty search, twenty webhooks, twenty api-keys, twenty files, twenty serverless
• Raw API access: twenty rest and twenty graphql commands

AI Agent Integration

This CLI is specifically designed for AI agent consumption. Agents like clawdbot wrap APIs as CLI tools that AI can invoke through shell commands. With this CLI, any AI agent can:

• Manage CRM records programmatically
• Create and configure custom objects/fields
• Set up webhooks and serverless functions
• Search across all objects
• Handle file attachments

The consistent command structure (<resource> <operation> [args] [options]) and JSON output mode (-o json) make it trivial for agents to parse and compose commands.

Distribution

Since it's TypeScript, it can be installed via npm:

npm install -g twenty-sdk
npx twenty-sdk <command>

Test Coverage

543 tests passing with 87%+ coverage. Ready for review and integration into twenty-sdk whenever you're ready!

Let me know if you'd like me to open a PR directly to twenty-sdk or if there's anything you'd like me to adjust first.

[salmonumbrella]

Hey @charlesBochet — any thoughts or updates on this?

With the CLI in TypeScript now (as requested), it'd be great to get this merged so the community can start using it. The nice thing is that it would let anyone's AI agent interact with Twenty right away, while you continue building out your own native AI agent features.

Would love to deploy this — let me know if there's anything blocking or if I should open a PR!

[charlesBochet]

@salmonumbrella this should be integrated in the twentyhq/twenty repository under packages/twenty-sdk. We are actively refactoring, give us a few days and we can discuss what can be integrated :)

@martmull fyi