---
name: cart-init
description: |
  Conversationally onboard a developer to the acommerce cart for coding
  agents. Signs them in, walks them through minting an API key from the
  dashboard, stores it as a Claude Code secret, shows them how to buy
  credits, and runs a demo cart call so they see the proxy working.
---

# acommerce cart — conversational onboarding

You are guiding a developer through setting up the acommerce cart, a
credit-metered proxy that fronts multiple provider APIs for coding agents.
The developer has just pasted an install prompt into Claude Code and is
ready to go. Walk them through every step. Use AskUserQuestion whenever you
need input. Keep explanations short.

## Step 1 — sign in and open the dashboard

Tell the user:

> "First, open the acommerce dashboard in your browser so you can mint an API
> key. I'll open it for you now."

Run the following command to open the dashboard in their default browser:

```bash
open "https://acommerce.dev/dashboard/settings/api-keys" 2>/dev/null || \
  xdg-open "https://acommerce.dev/dashboard/settings/api-keys" 2>/dev/null || \
  echo "Open this URL manually: https://acommerce.dev/dashboard/settings/api-keys"
```

If they are not signed in, Supabase auth will redirect them to `/login`.
Wait for them to confirm they are signed in. Ask:

> "Let me know when you're signed in and looking at the API Keys page."

## Step 2 — mint an API key

Tell the user:

> "Click **Create key**, name it 'claude-code' (or whatever you want), then
> copy the raw key that appears. It will only be shown once. Paste it back
> here when you have it."

Use AskUserQuestion with a single free-response option to collect the key.
The raw key starts with `ak_` followed by hex characters. Validate that it
matches the pattern `ak_[a-f0-9]{64}` before storing.

If the pattern doesn't match, ask them to paste it again, telling them the
expected shape.

## Step 3 — store the key as a Claude Code secret

Run:

```bash
claude-code secrets set ACOMMERCE_API_KEY "<the key they pasted>"
```

Confirm with the user:

> "Stored. Your key is now available as `process.env.ACOMMERCE_API_KEY` in
> any Claude Code session."

If the `claude-code` CLI isn't available or the command fails, fall back to
writing to `~/.claude/env` or instructing the user to add it to their shell
profile. Pick whichever matches their environment.

## Step 4 — buy starter credits

Tell the user:

> "You'll need credits to call the proxy. New accounts start with $0 — you
> can top up $10, $25, or $100 via Stripe Checkout from the dashboard. I'll
> open the credits page now."

Run:

```bash
open "https://acommerce.dev/dashboard/cart/credits" 2>/dev/null || \
  xdg-open "https://acommerce.dev/dashboard/cart/credits" 2>/dev/null || \
  echo "Open this URL manually: https://acommerce.dev/dashboard/cart/credits"
```

Ask:

> "Let me know when you've completed a top-up and your balance shows
> credits. If you want to skip this and come back to it later, say 'skip'
> and I'll run the demo anyway — but the demo will fail with 402 if you
> have zero credits."

Wait for confirmation before proceeding.

## Step 5 — update CLAUDE.md with usage notes

Add a section to the project's `CLAUDE.md` (create the file if needed)
describing how to use the acommerce SDK:

```markdown
## acommerce cart

This project uses the acommerce cart — a credit-metered proxy for coding
agents. The API key lives in the `ACOMMERCE_API_KEY` Claude Code secret.

Usage example:

\`\`\`ts
import { Acommerce } from "acommerce";

const ac = new Acommerce(process.env.ACOMMERCE_API_KEY!);

// List available providers in the cart
const { providers } = await ac.cart.providers.list();

// Check your credit balance
const { balance_cents } = await ac.cart.credits.balance();
\`\`\`

Cart dashboard: https://acommerce.dev/dashboard/cart
Providers catalog: https://acommerce.dev/dashboard/cart
```

## Step 6 — install the SDK and verify

Install the SDK if it isn't already:

```bash
npm install acommerce
```

Then run a short script that lists the providers visible in the cart. This
confirms the key is working end-to-end without spending credits.

```bash
node -e '
const { Acommerce } = require("acommerce");
(async () => {
  const ac = new Acommerce(process.env.ACOMMERCE_API_KEY);
  const { providers } = await ac.cart.providers.list();
  console.log("providers:", providers.map(p => p.id + " (" + p.status + ")"));
  const { balance_cents } = await ac.cart.credits.balance();
  console.log("balance cents:", balance_cents);
})().catch(err => { console.error(err.message); process.exit(1); });
'
```

If it prints a list of providers and your balance, celebrate briefly:

> "Your cart is live. You have an API key, credits, and working access to
> every provider in the catalog. Call any live provider through the SDK or
> the raw API."

If it fails with `AuthError`, the key probably wasn't stored correctly —
go back to step 3 and re-store.

## Done

Tell the user:

> "That's everything. You have:
> - An acommerce API key stored in Claude Code secrets
> - Credits in your account
> - The SDK installed and working
> - A CLAUDE.md note so future Claude Code sessions know how to use the cart
>
> Check the provider catalog at https://acommerce.dev/dashboard/cart. Run
> `/cart-init` again if you ever need to re-onboard on a new machine."