Imported from bcharleson/twenty-agent-cli (AGENTS.md). Install upstream with npx skills add bcharleson/twenty-agent-cli. Copyright stays with the author.

AGENTS.md — twenty-agent-cli

Instructions for AI agents and developers using twenty-agent-cli after npm install twenty-agent-cli.

What this package is

twenty-agent-cli makes any Twenty CRM instance (cloud or self-hosted) operable from:

1. Shell — twenty-agent CLI
2. AI assistants — twenty-agent serve (stdio MCP server)

It is not the official Twenty app builder (twenty-sdk). Use this package to read/write CRM data and run Twenty's 250+ workspace tools.

Only two values change per deployment:

TWENTY_BASE_URL=https://crm.example.com   # no trailing slash
TWENTY_API_KEY=your_api_key               # Settings → API & Webhooks

Install

npm install -g twenty-agent-cli
# or use npx without global install:
npx twenty-agent-cli ping

Create .env or export env vars (see .env.example in the repo).

Verify:

twenty-agent ping

Agent setup (Cursor, Claude Desktop, etc.)

Add an MCP server entry:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "npx",
      "args": ["-y", "twenty-agent-cli", "serve"],
      "env": {
        "TWENTY_BASE_URL": "https://crm.example.com",
        "TWENTY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

For a local dev checkout, use node /path/to/twenty-agent-cli/bin/twenty-agent.js serve instead.

Skills — how agents should use Twenty

Skill 1: Orient before acting

Always start a new session with:

1. twenty_ping — confirm credentials and workspace
2. twenty_list_objects — discover object plural names (lightweight)
3. twenty_describe_object (or twenty-agent describe <object>) — before any create/update on an object you have not used this session

Never guess object names or field shapes. Custom objects appear in list/describe immediately after creation.

For creates, prefer twenty_rest_example then edit the skeleton (FK *Id fields, CURRENCY amountMicros, SELECT enums). See docs/AGENT-UX-ROADMAP.md.

Skill 2: Choose the right API layer

Skill 3: Workspace catalog workflow (recommended for CRM tasks)

Twenty exposes 250+ named tools per workspace (find_companies, create_person, …). Access them through a fixed pipeline:

twenty_tool_catalog  →  twenty_tool_learn  →  twenty_tool_execute

Rules:

• Never guess tool names. Always call twenty_tool_catalog first.
• Never guess argument shapes. Call twenty_tool_learn with exact tool names before twenty_tool_execute.
• For workflows, dashboards, or imports, call twenty_load_skills with relevant skill names (e.g. workflow-building) before executing.

Example mental model:

1. twenty_tool_catalog        # browse categories
2. twenty_tool_learn          # toolNames: ["find_companies"]
3. twenty_tool_execute        # toolName: "find_companies", arguments: { limit: 10 }

Skill 4: Pagination and filters (REST list)

When using twenty_rest_list or rest get without an ID:

Skill 5: Batch and upsert operations

Rate limits: 100 requests/minute, 60 records/batch (Twenty API docs).

Skill 6: When stuck

1. twenty_search_help — search Twenty documentation
2. twenty_rest_raw / twenty_metadata_raw — escape hatch for undocumented paths
3. Fall back to twenty_tool_catalog for workspace-native operations

CLI quick reference

Full flag listing: docs/COMMAND-REFERENCE.md

# Core
twenty-agent ping | config | serve

# Core REST
twenty-agent rest get|post|patch|patch-many|delete|delete-many|batch|restore|restore-many|group-by|duplicates|merge|raw ...

# Metadata REST
twenty-agent metadata list <resource> [--limit] [--starting-after] [--ending-before]
twenty-agent metadata raw <method> <path> [json]

# GraphQL
twenty-agent graphql core|metadata <query> [--vars json]
twenty-agent graphql objects

# Workspace tools (/mcp)
twenty-agent tools list|catalog|learn|call|skills|search ...

MCP tool catalog (stdio)

Error handling

• Failed API calls return JSON error bodies in MCP text content.
• HTTP 401/403: invalid or under-scoped API key — check Settings → Members → Roles.
• 404 on object: wrong plural name — rerun twenty_list_objects.
• Unknown catalog tool: rerun twenty_tool_catalog; do not invent names.

Provisioning a new client instance

1. Set TWENTY_BASE_URL and TWENTY_API_KEY for that instance
2. twenty-agent ping
3. Update MCP config env vars
4. No code or package changes required

Related docs

Do not confuse with