magecli

Why magecli?

Give your AI agent direct access to Magento

AI coding agents like Claude Code and Codex CLI are transforming how developers work with complex systems. But they can only use what they can reach. Without magecli, asking an agent to "check if SKU X is in stock" or "find all products under $50" means the agent has no way to answer — it can't call the Magento REST API on its own.

magecli bridges that gap. It ships with prebuilt skill definitions that plug directly into Claude Code and Codex. Once installed, your agent automatically discovers magecli and can query products, browse categories, check inventory, inspect CMS content, and explore store configuration — all through simple CLI commands it already knows how to run.

The skill files teach the agent the full command syntax, filter operators, output modes, and context management — so it writes correct commands on the first try without you having to explain the Magento API.

Just as useful without an agent

Magento 2's REST API is powerful but verbose. A simple product lookup requires constructing complex searchCriteria query parameters, managing authentication headers, and parsing nested JSON. magecli wraps all of that in a clean, composable CLI that feels like gh or aws-cli.

Why a CLI instead of MCP?

An MCP server is another way to connect an AI agent to Magento, but it comes with overhead: a Node or Python runtime, a long-lived server process, JSON-RPC transport configuration, and custom code to maintain. Every tool call also burns tokens on the MCP protocol framing before you even get to the Magento data.

magecli is a static binary. There's no runtime, no server, no process to keep alive. It works in CI, Docker, SSH sessions, and local dev — anywhere you can run a command. The agent calls it like any other CLI tool, gets compact JSON back, and moves on. Less infrastructure, fewer tokens per interaction, and nothing to babysit.

Installation

Quick Install Recommended

The install scripts auto-detect your OS and architecture, download the latest release, verify the checksum, and place the binary in your PATH.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/atlanticbt/magecli/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/atlanticbt/magecli/main/install.ps1 | iex

# Custom install directory and version
curl -fsSL https://raw.githubusercontent.com/atlanticbt/magecli/main/install.sh | sh -s -- --dir ~/.local/bin --version v1.0.0

From Go

go install github.com/atlanticbt/magecli/cmd/magecli@latest

From Source

git clone https://github.com/atlanticbt/magecli.git
cd magecli
make build
# Binary at bin/magecli

From GitHub Releases (manual)

Download the archive for your platform from GitHub Releases and extract the binary to a directory in your PATH.

Verify the installation:

magecli --version

Updating

magecli can update itself to the latest release directly from GitHub. The update command downloads the correct binary for your platform, verifies the SHA-256 checksum, and replaces the current binary in place.

# Update to the latest release
magecli update

# Reinstall even if already on the latest version
magecli update --force

Setup Tutorial

Four steps to your first query.

magecli auth login https://store.example.com --token <access-token>

magecli auth login https://store.example.com --token <access-token> --allow-insecure-store

export MAGECLI_TOKEN=<access-token>

magecli context create production --host store.example.com --store-code default --set-active

magecli context create dev --host dev.example.com --allow-writes --set-active

# List products
magecli product list --limit 10

# Search by name
magecli product search "blue shirt"

# View product details as JSON
magecli product view SKU123 --json

# Browse the category tree
magecli category tree

# Check inventory
magecli inventory status SKU123

Command Reference

Global Flags

Products

Listing & Searching

# List all products (default limit: 50)
magecli product list

# Quick name search
magecli product search "outdoor shirt"

# Filter with operators
magecli product list --filter "price gt 100" --filter "status eq 1"

# Sort and paginate
magecli product list --sort "price:ASC" --limit 20 --page 2

# Find by URL key
magecli product url blue-outdoor-jacket

Viewing Details

# Full product details
magecli product view SKU123

# Just the name
magecli product view SKU123 --json --jq '.name'

# Product images
magecli product media SKU123

Configurable Products

# List simple variants of a configurable
magecli product children PARENT-SKU

# List configurable options (color, size, etc.)
magecli product options PARENT-SKU

Categories

# Full category tree
magecli category tree

# From a specific root, limited depth
magecli category tree --root 37 --depth 2

# View a single category
magecli category view 42

# Products in a category
magecli category products 42 --limit 20

Attributes

# View an attribute definition
magecli attribute view color

# List option values for a select/dropdown attribute
magecli attribute options color

# List all attribute sets
magecli attribute sets

Inventory

# Check stock status
magecli inventory status SKU123

# JSON for scripting
magecli inventory status SKU123 --json

Returns quantity, in-stock status, min/max sale quantities, and other stock configuration.

Store Configuration

# List all store views
magecli store views

# Show config for all stores
magecli store config

# Filter to a specific store code
magecli store config default

# List store groups and websites
magecli store groups
magecli store websites

Config includes locale, currency, timezone, weight unit, and all base URLs (standard, secure, media, static).

System Configuration

Query Magento system configuration values for auditing and environment comparison.

# List all config values as path=value
magecli config list

# Filter to a specific section
magecli config list --filter web/secure
magecli config list --filter currency

# Get a specific config path
magecli config get general/locale/code
magecli config get web/secure/base_url

# Compare environments
diff <(magecli -c staging config list) <(magecli -c prod config list)
diff <(magecli -c staging config dump --json) <(magecli -c prod config dump --json)

Config paths follow the Magento convention (e.g., general/locale/code, web/unsecure/base_url, currency/options/base). Output is grouped by store scope.

Promotions

View catalog price rules, cart price rules, and coupon codes. All list commands support --filter, --sort, --limit, and --page.

Catalog Price Rules

Applied to products before they are added to the cart.

# List all catalog rules
magecli promo catalog-rule list

# Only active rules
magecli promo catalog-rule list --filter "is_active eq 1"

# View rule details
magecli promo catalog-rule view 42 --json

Cart Price Rules

Applied at checkout. May include coupon codes, free shipping, or buy-X-get-Y offers.

# List all cart rules
magecli promo cart-rule list

# Active rules with coupon codes
magecli promo cart-rule list --filter "is_active eq 1" --json

# View full details
magecli promo cart-rule view 5

Coupons

View coupon codes, usage stats, and expiration dates.

# List all coupons
magecli promo coupon list

# Search by code
magecli promo coupon list --filter "code like %SUMMER%"

# Coupons for a specific rule
magecli promo coupon list --filter "rule_id eq 5"

# View coupon details
magecli promo coupon view 1

CMS Pages & Blocks

# List CMS pages
magecli cms page list
magecli cms page list --filter "identifier like %home%"

# View a page (metadata only)
magecli cms page view 11

# Include HTML content
magecli cms page view 11 --content

# Blocks work the same way
magecli cms block list
magecli cms block view 31 --content

Raw API Access

For endpoints without a first-class command, use the api escape hatch. Paths are relative to /rest/{store_code}/.

# GET requests work on any context
magecli api /V1/store/storeViews --json
magecli api /V1/products -P "searchCriteria[pageSize]=5" --json

# Custom headers
magecli api /V1/products -H "X-Custom: value"

# Create a write-enabled context
magecli context create dev --host dev.example.com --allow-writes --set-active

# Now POST/PUT/DELETE are allowed
magecli api /V1/products -X POST -d '{"product": {"sku": "new", "name": "New"}}'
magecli api /V1/products/SKU123 -X DELETE

Output Formats

Every command supports multiple output modes.

JSON

magecli product list --json

YAML

magecli product view SKU123 --yaml

jq Filtering

# Extract SKUs
magecli product list --json --jq '.items[].sku'

# Build custom objects
magecli product list --json --jq '.items[] | {sku, name, price}'

Go Templates

magecli product list --json --template '{{range .items}}{{.sku}} - {{.name}} (${{.price}})
{{end}}'

Filtering & Sorting

The --filter flag uses a simple "field operator value" syntax. Multiple filters are ANDed together.

# Single filter
magecli product list --filter "name like %shirt%"

# Multiple filters (AND)
magecli product list --filter "price gt 50" --filter "status eq 1"

# Sorting (field:direction)
magecli product list --sort "price:ASC" --sort "name:DESC"

# Pagination
magecli product list --limit 20 --page 3

Available Operators

Context Management

Contexts let you manage multiple Magento stores and switch between them instantly.

# Create contexts for different environments
magecli context create production --host store.example.com --store-code default --set-active
magecli context create staging --host staging.example.com --store-code default
magecli context create dev --host dev.example.com --allow-writes

# Switch contexts
magecli context use staging

# List all (* = active)
magecli context list

# Override per-command
magecli product list --context production

# Delete
magecli context delete dev

Config File

Stored at ~/.config/magecli/config.yml. Tokens are never written here — they live in the OS keyring.

version: 1
active_context: production
contexts:
  production:
    host: store.example.com
    store_code: default
  staging:
    host: staging.example.com
    store_code: default
  dev:
    host: dev.example.com
    store_code: default
    allow_writes: true
hosts:
  store.example.com:
    base_url: https://store.example.com
  staging.example.com:
    base_url: https://staging.example.com
  dev.example.com:
    base_url: https://dev.example.com

Environment Variables

AI Agent Integration

magecli ships with skill definitions that let AI coding agents (Claude Code, Codex CLI) discover and use it automatically.

Installing the Skill

# Install globally for Claude Code
npx skills add atlanticbt/magecli

Once installed, your AI agent can run commands like:

# Agent prompt: "What products cost over $100?"
# Agent runs:
magecli product list --filter "price gt 100" --json --jq '.items[] | {sku, name, price}'

Skill Files

Use Cases

magecli shines when paired with AI coding agents. Here are common prompts you can give Claude Code (or any agent with the magecli skill installed) and what happens behind the scenes.

Catalog Exploration

Troubleshooting & Debugging

Configuration & Environment Management

Promotions & Pricing

Content Auditing

Data Export & Reporting

Combining with Other Tools

magecli becomes even more powerful when your agent has access to other CLI tools and MCP servers: