Agent-first GraphQL CLI for Vendure. Discover, authenticate, and execute GraphQL operations from the command line or via AI agents.

Arnold uses live schema introspection — no generated files, no snapshots, nothing to maintain. The running API is always the source of truth.

• Schema discovery — find operations and inspect types via targeted introspection, not full schema dumps
• Authentication — login once, token persists across commands
• Execution — run queries and mutations with inline or file-based GraphQL
• Agent-first — ships as a Claude Code skill with /arnold slash command
• Zero maintenance — reads from the live API, nothing goes stale
• Single binary — compiled with Bun, no runtime dependencies

curl -fsSL https://raw.githubusercontent.com/HouseinIsProgramming/arnold/main/install.sh | bash

If the above fails due to CDN caching, use:

gh api repos/HouseinIsProgramming/arnold/contents/install.sh --jq '.content' | base64 -d | bash

This installs the arnold binary and the Claude Code skill.

# Discover what operations exist
arnold schema ops --api shop --filter order

# Inspect an input type
arnold schema type --api admin UpdateOrderInput

# Authenticate
arnold auth login --api admin --email [email protected] --password secret

# Execute a query
arnold exec --api admin --query '{ orders(options: { take: 5 }) { totalItems items { id code } } }'

# Check auth status
arnold auth status

After installing, the /arnold slash command is available in Claude Code:

/arnold find all order-related mutations in the admin API
/arnold create 5 test orders for customer 12
/arnold authenticate as admin and list recent products

The agent will discover the schema, ask for any missing context (IDs, credentials), authenticate, and execute — typically in 2-3 steps.

List queries and mutations via introspection.

arnold schema ops --api shop                        # all shop operations
arnold schema ops --api admin --filter order         # filtered by keyword
arnold schema ops --api shop --compact               # names only
arnold schema ops --api admin --filter offer --json  # JSON output

Describe a specific GraphQL type — works with objects, inputs, enums, and unions.

arnold schema type --api shop Customer
arnold schema type --api admin CreateUserNotificationInput
arnold schema type --api admin NativeAuthenticationResult  # shows union members

Manage authentication sessions.

arnold auth login --api admin --email [email protected] --password secret
arnold auth login --api shop --email [email protected] --password secret
arnold auth status          # check active sessions
arnold auth logout --api admin

Tokens are stored in ~/.arnold/ and automatically used by arnold exec.

Execute GraphQL queries and mutations.

# Inline query
arnold exec --api shop --query '{ activeCustomer { id emailAddress } }'

# With variables
arnold exec --api admin --query 'mutation ($id: ID!) { deleteOrder(id: $id) { result } }' \
  --variables '{"id": "123"}'

# From file
arnold exec --api shop --file ./my-query.graphql --variables '{"limit": 10}'

# JSON output for parsing
arnold exec --api admin --query '{ orders { totalItems } }' --json

Arnold resolves the API URL with the following priority:

1. ARNOLD_SHOP_API / ARNOLD_ADMIN_API env vars (highest priority)
2. .arnoldrc file (searched up from current directory)
3. PORT env var — follows Vendure convention (http://localhost:$PORT/shop-api)
4. Default: http://localhost:3000/shop-api and http://localhost:3000/admin-api

ARNOLD_SHOP_API=http://localhost:3000/shop-api
ARNOLD_ADMIN_API=http://localhost:3000/admin-api

For multi-step workflows that aren't obvious from the schema alone, add a CLAUDE.md to the plugin directory:

libs/shared/vendure-plugins/<plugin-name>/CLAUDE.md

Include the API flow (numbered steps), auth requirements, and gotchas. Do not duplicate type definitions — the schema handles that.

# Reviews Plugin

## API Flow
1. Auth as shop customer
2. `submitProductReview` with productId, rating, body
3. Admin moderates: `approveProductReview(id)` or `rejectProductReview(id)`
4. Approved reviews visible via `productReviews(productId)`

## Gotchas
- Customers can only review products they have purchased
- Approving a review recalculates the product's average rating

Claude Code automatically picks up these files when working in the plugin directory.

git clone https://github.com/HouseinIsProgramming/arnold.git
cd arnold
bun install
bun run build        # compile to ./arnold binary
bun run build:all    # cross-compile for darwin-arm64, darwin-x64, linux-x64

Tag a version and push — GitHub Actions builds binaries and creates a release:

git tag v0.1.0
git push --tags

MIT