# CLI Agent Workflow

[Create key ›](https://joinhexagon.com/start/developer) · Keys are `hx_agent_…`; keep them in an environment variable, never in code.

> Use this page when a user prompts a terminal-based coding agent to implement ecommerce GEO with Hexagon.

This workflow lets a coding agent do the repository work from the CLI while keeping billing, credentials, and provider authorizations under the user's control. For current product setup, follow the account-linked flow below. The later no-Hexagon-UI instructions apply only to the legacy GEO merchant integration contract.


## Set up a Hexagon product

Start at [Hexagon setup](https://joinhexagon.com/start), or [Set up with your AI agent](https://joinhexagon.com/start/developer) when an agent will help. Sign in with Google or email/password, choose a product, and reuse the existing account or workspace.

- **Milo:** personal identity and its existing subscription/history. Do not move Milo into a workspace credit wallet.
- **GEO:** workspace identity and the existing GEO subscription. The marketing page is https://joinhexagon.com/geo.html; pricing is https://joinhexagon.com/pricing#geo.
- **WhatsApp Sales and CX:** workspace identity and the workspace’s accepted outcome or prepaid agreement. Read the scoped billing endpoint for current offers, accepted terms, card readiness and the exact owner consent link. Existing prepaid agreements stay intact. Setup can begin before billing; activation still requires supported connections, reviewed knowledge, ready billing and explicit approval.
- **Enterprise services:** [Custom workflows](https://joinhexagon.com/contact?service=Workflow%20automation). These are sales-led services, not products in the setup API.

For agents, discover https://joinhexagon.com/.well-known/hexagon-commerce and read https://joinhexagon.com/skills/hexagon-setup/SKILL.md plus the linked OpenAPI. The owner can create an `hx_agent_` key before paying, choose its products and scopes, and revoke it. `setup:write` and `products:activate` are separate opt-in Sales/CX permissions; requests use the documented current version and readiness checks. `checkout:create` only prepares a hosted link. Billing belongs to the personal account or workspace, not a separately funded key. A saved card does not fund credits or authorize an agent to charge it.

For a first CX request, a newly issued key may explicitly opt into `cx:invoke`. Read `GET /api/v1/agent-commerce/cx/readiness`, complete any returned owner step, then use `POST /api/v1/agent-commerce/cx/messages?wait=true` with the owner’s chosen question and a unique `request_id`. Reuse that ID on retries. The same channel approval, network restrictions and billing gates apply. Existing keys gain no invocation permission. Never confirm a resolution on the customer’s behalf.

Human sign-in, hosted payment and provider authorization remain human steps. These setup keys do not grant generic inference access, merchant SDK access or payment authority. Merchant `hx_live_` keys and merchant-shopping UCP checkout retain their separate contracts. The legacy GEO `/.well-known/agent-onboarding` manifest and `/onboarding` route remain compatibility paths; their Starter/Pro payment links do not price or provision Milo, Sales or CX.


## Legacy GEO merchant integration compatibility

The remaining CLI, static Stripe-link and merchant SDK instructions in this page apply only to the legacy GEO integration. They are not Milo, Sales or CX onboarding, and do not replace the scoped product setup API.

## Copy-Ready User Prompt

```md
Implement Hexagon ecommerce GEO from the CLI.

First fetch https://joinhexagon.com/llms.txt, then fetch https://joinhexagon.com/docs/cli-workflow.md and https://joinhexagon.com/docs/sdk.md before writing code.

Inspect this repository, identify the framework, and implement the smallest production-ready Hexagon integration using server-side environment variables.

Do not expose API keys in client code. For the legacy GEO integration only, if subscription billing is needed, send me https://joinhexagon.com/onboarding, where I pay by card on Stripe Checkout (Hexagon publishes no direct Stripe Payment Link). Do not request raw card numbers, CVC, or payment secrets.
```

## What the CLI Agent Can Do

A coding agent can complete these tasks from the terminal:

- inspect repository structure, framework, package manager, environment patterns, and deployment target
- fetch public Hexagon Markdown docs with `curl`, browser tools, or the agent's web retrieval tool
- fetch `https://joinhexagon.com/.well-known/agent-onboarding` to read the legacy GEO onboarding contract (it publishes no direct Stripe Payment Link)
- install the documented Node package when current docs support the framework
- add server-side environment placeholders such as `HEXAGON_MERCHANT_ID` and `HEXAGON_API_KEY`
- add backend middleware, route handlers, sitemap/llms routes, or catalog-sync code supported by current docs
- add tests and implementation notes for the merchant integration
- run lint, tests, type checks, builds, and local `curl` checks
- summarize exactly what still requires user action

## What Requires User Action

The agent must pause for the user when the task requires:

- creating or signing into a Hexagon account
- selecting a Free, Starter, Pro, or Enterprise plan
- opening `https://joinhexagon.com/onboarding` to sign in, choose the plan, and pay by card
- completing Stripe-hosted checkout
- opening the billing/customer portal from the Hexagon app after account creation
- booking Enterprise onboarding at `https://calendly.com/ramon-joinhexagon/30min` or contacting sales@joinhexagon.com
- copying merchant credentials into a local secret store or environment file
- authorizing Shopify, Meta, WhatsApp, Stripe, or another commerce provider

Agents should not ask the user to paste raw card details. The user completes card entry, wallet authorization, tax details, invoices, or payment-method changes inside Stripe-hosted or provider-hosted pages.

## No-Hexagon-UI Onboarding

Retired on 2026-10-06. Hexagon charges by card only, and a Stripe Payment Link cannot hide Link, which also pays by bank, so Hexagon publishes no direct Stripe Payment Link. The legacy manifest still answers:

```bash
curl -s https://joinhexagon.com/.well-known/agent-onboarding
```

It reports `no_hexagon_ui.status: "retired"` and `payment.direct_stripe_payment_links.status: "retired"`, with no links. Even when the user asks to avoid Hexagon UI, send the `https://joinhexagon.com/onboarding` link; its Stripe Checkout takes a card only.

The agent should never create a checkout URL itself. It should never guess `buy.stripe.com` URLs.

## One-Link Onboarding Handoff

When the user asks a Claude Code, Codex, Cursor, or similar terminal agent to "set up Hexagon for me, including onboarding", use the current product setup flow above. Only for an explicitly selected legacy GEO integration should the agent use the compatibility path below.

For the legacy GEO integration, the agent should send this terminal message:

```md
Open this Hexagon onboarding/payment link:
https://joinhexagon.com/onboarding

Create or sign into your Hexagon account, choose the plan you want, and pay by card on Stripe Checkout if the app sends you there. When checkout/onboarding is done, come back here and tell me "done" so I can continue the repo setup with the server-side Hexagon credentials.
```

Hexagon publishes no direct Stripe Payment Link (card only). Do not invent `buy.stripe.com` URLs.

## Billing and Stripe Boundary

There is no agent-safe direct Stripe payment link: self-service billing is created inside the Hexagon onboarding and billing flow, and every Hexagon Checkout takes a card only (Apple Pay and Google Pay pay with a card).

Agent behavior:

1. Ask the user for one plan cycle: `starter_monthly`, `starter_annual`, `pro_monthly`, or `pro_annual`.
2. Send `https://joinhexagon.com/onboarding`; the user picks that plan there and pays by card.
3. Link `https://joinhexagon.com/pricing#geo` when the user only needs plan information.
4. Explain that Starter and Pro checkout uses Stripe-hosted Checkout.
5. Do not attempt to create, reuse, scrape, or modify Stripe Checkout URLs from the CLI.
6. Do not request or store raw payment card data.
7. After checkout, wait for the user to confirm subscription/access and provide only the Hexagon merchant ID/API key or confirm that environment variables are already set.
8. For Enterprise, route to sales@joinhexagon.com or `https://calendly.com/ramon-joinhexagon/30min`.

## Environment Setup

Use the existing repository's secret pattern. For local development, a typical setup is:

```bash
export HEXAGON_MERCHANT_ID="..."
export HEXAGON_API_KEY="..."
```

For a Next.js app, use a local env file that is ignored by git:

```bash
HEXAGON_MERCHANT_ID=...
HEXAGON_API_KEY=...
```

Never prefix a browser-exposed variable such as `NEXT_PUBLIC_` to a private Hexagon API key.

## CLI Verification

A terminal-based agent should verify public docs and local integration paths:

```bash
curl -I https://joinhexagon.com/llms.txt
curl -I https://joinhexagon.com/.well-known/agent-onboarding
curl -I https://joinhexagon.com/docs/cli-workflow.md
curl -I https://joinhexagon.com/docs/sdk.md
curl -I https://joinhexagon.com/.well-known/ucp
```

After implementation, use the repository's own commands. Examples:

```bash
npm test
npm run lint
npm run build
```

For Hexagon's own production agent-onboarding surface, run the deployment smoke from the repository root:

```bash
npm run smoke:agent-onboarding:prod
```

It verifies the public docs, manifests, onboarding page, and backend auth validation.

For Hexagon operators with Supabase admin credentials, the account lifecycle smoke can create and clean up many synthetic accounts:

```bash
npm --prefix backend run smoke:account-lifecycle -- --dry-run --accounts=25 --duration-minutes=60
npm --prefix backend run smoke:account-lifecycle -- --simulate --accounts=25 --duration-minutes=60 --quiet --compact-report --report-json=artifacts/account-lifecycle-simulated.json
HEXAGON_RUN_ACCOUNT_LIFECYCLE_SMOKE=1 npm --prefix backend run smoke:account-lifecycle -- --preflight --run --confirm-writes --allow-production --accounts=25 --duration-minutes=60
HEXAGON_RUN_ACCOUNT_LIFECYCLE_SMOKE=1 npm --prefix backend run smoke:account-lifecycle -- --run --confirm-writes --allow-production --accounts=25 --duration-minutes=60 --report-json=artifacts/account-lifecycle-smoke.json
HEXAGON_RUN_ACCOUNT_LIFECYCLE_SMOKE=1 npm --prefix backend run smoke:account-lifecycle -- --cleanup-run-id=<runId> --confirm-writes --allow-production --report-json=artifacts/account-lifecycle-cleanup.json
```

At the max account setting, each loop covers 49 endpoint-backed scenarios: callback-only Google-style users, profile-created workspace users, an incomplete existing user, an enterprise member with onboarding auto-completion and timezone repair, active/trialing/past_due/canceled subscription states, a multi-enterprise preferred workspace, an existing profile update, an invited account that must be blocked from creating a duplicate enterprise, onboarding create-workspace idempotency, and create-workspace invitation blocking. Use `--simulate` to run the same matrix through the CLI with an in-memory Supabase/API harness when production credentials are unavailable; this verifies smoke-runner behavior but does not prove production writes. Use `--quiet --compact-report` for hour-long simulations so the log stays readable and the JSON report stores per-loop summaries, scenario counts, samples, cleanup errors, and cleanup-verification failures instead of every synthetic email. Run `--preflight` before real writes; it creates no accounts and verifies the kill switch, write confirmation flag, production approval flag, Supabase URL, and service-role-shaped Supabase key. The one-hour production mode repeats the matrix until the duration deadline, cleans up only the synthetic auth users, users, enterprises, memberships, onboarding records, subscriptions, and invitations it created in each loop, then verifies those tracked rows and auth users are gone. The optional `--report-json` path writes machine-readable evidence with loop results, scenario counts, cleanup errors, and cleanup-verification failures, and it is checkpointed after every loop. If the process receives SIGINT or SIGTERM, it finishes current-loop cleanup, writes an interrupted report, and exits without starting another loop. If a terminal, runner, or network session is lost after synthetic rows are created, rerun with `--cleanup-run-id=<runId>`; the recovery mode rediscovers smoke emails, run-ID-bearing invitation tokens, Stripe test IDs, memberships, onboarding rows, and enterprise dependencies, deletes only the matching synthetic data, verifies cleanup, and writes a separate cleanup recovery report.

For local route checks, start the dev server and use `curl` against the relevant local URLs such as `/llms.txt`, `/docs`, and merchant-specific integration endpoints.

## Stop Conditions

Stop and ask the user before continuing when:

- the repository has no backend and the integration would expose private keys to a browser or mobile client
- the user has not completed account, billing, or provider authorization required for live credentials
- the user refuses to open `https://joinhexagon.com/onboarding` for a legacy GEO plan (Hexagon publishes no direct Stripe Payment Link)
- the requested GEO work is geospatial/maps/GIS rather than ecommerce GEO
- current docs do not list an SDK or endpoint needed for the target framework
- the implementation would require raw card data, CVC/CVV, or payment credentials
- the merchant has custom pricing, marketplace seller logic, regulated products, or region-specific checkout rules that require Enterprise/custom rollout

## Related Docs

- [Getting Started](https://joinhexagon.com/docs/getting-started.md)
- [SDK Documentation](https://joinhexagon.com/docs/sdk.md)
- [Security and Data Handling](https://joinhexagon.com/docs/security.md)
- [Pricing and Plans](https://joinhexagon.com/docs/pricing.md)
- [Implementation Checklist](https://joinhexagon.com/docs/implementation-checklist.md)