@raptorr/vendure-pi

Pi agent extension for Vendure e-commerce management. Connect to your Vendure instance and manage products, orders, customers, and more through natural language.

Requires vendure-mcp-graphql.

Installation

npm install -g vendure-mcp-graphql pi

# Then install this extension in your project:
cd /path/to/your/vendure-project
pi install /path/to/vendure-pi -l

Environment

export VENDURE_API_KEY="your-api-key"
export ADMIN_API_URL="http://localhost:3000/admin-api"   # optional
export SHOP_API_URL="http://localhost:3000/shop-api"     # optional

Usage

pi --provider quotio --model gemini-3.1-flash-lite

Then type commands like:

list 5 channel listings
show order summaries
how many products do we have?
list admin users
create a new product called "Test Product"

Built-in Tools

| Tool | Description | |------|-------------| | vendure_admin_query | Execute any GraphQL query on Admin API | | vendure_admin_mutation | Execute any GraphQL mutation on Admin API | | vendure_shop_query | Execute any GraphQL query on Shop API | | vendure_shop_mutation | Execute any GraphQL mutation on Shop API | | vendure_list_admin_operations | Discover all Admin API queries and mutations | | vendure_get_admin_schema | Full Admin API introspection | | vendure_list_shop_operations | Discover all Shop API queries and mutations | | vendure_get_shop_schema | Full Shop API introspection |

Custom Tools

Define your own tools by mapping GraphQL queries/mutations to named commands. Tools are loaded from three locations (globals override earlier ones):

1. tools/default-tools.json — shipped with the package (updates with new versions)
2. ~/.pi/vendure-custom-tools.json — global user tools (shared across projects)
3. .pi/vendure-custom-tools.json — project tools (shared with your team via git)

Format

{
  "tools": [
    {
      "name": "last_orders",
      "label": "Last Orders",
      "description": "List the 5 most recent orders",
      "adminQuery": "query { orders(options: { take: 5 sort: { createdAt: DESC } }) { items { id code state total currencyCode customer { firstName lastName } } } }"
    },
    {
      "name": "mark_shipped",
      "label": "Mark Order Shipped",
      "description": "Transition an order to Shipped state",
      "adminMutation": "mutation($id: ID!) { transitionOrderToState(id: $id, state: \"Shipped\") { id state } }"
    }
  ]
}

Each tool has:

| Field | Description | |-------|-------------| | name | Unique tool name (prefix vendure_ is added automatically) | | label | Display name shown to the agent | | description | What the tool does | | adminQuery | GraphQL query for Admin API read operations | | shopQuery | GraphQL query for Shop API read operations | | adminMutation | GraphQL mutation for Admin API write operations | | shopMutation | GraphQL mutation for Shop API write operations |

Use exactly one of the four API fields per tool.

Example: Project Tools

Create .pi/vendure-custom-tools.json in your Vendure project:

{
  "tools": [
    {
      "name": "daily_revenue",
      "label": "Daily Revenue",
      "description": "Total revenue from orders placed today",
      "adminQuery": "query { orders(options: { filter: { orderPlacedAt: { after: \"2026-01-01T00:00:00Z\" } } }) { items { total totalWithTax currencyCode } } }"
    }
  ]
}

New tools appear automatically on next pi run — no restart needed.

License

MIT