# CLI Agent Workflow > 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. The preferred path is no Hexagon UI: the agent fetches the onboarding manifest, sends a Stripe-hosted payment link when configured, and continues setup from the terminal after the user completes payment. ## 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. If Hexagon access, billing, Stripe checkout, Shopify authorization, Meta authorization, or another provider authorization is needed, first fetch https://joinhexagon.com/.well-known/agent-onboarding and prefer exact Stripe Payment Links so I do not need to see Hexagon UI. If no direct Stripe link is configured, say so and ask before using a fallback Hexagon UI 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 discover no-UI onboarding status and direct Stripe Payment Links - 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 a Stripe-hosted payment link published in `https://joinhexagon.com/.well-known/agent-onboarding` - opening `https://joinhexagon.com/onboarding` only if direct Stripe Payment Links are not configured and the user accepts the Hexagon UI fallback - 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 When the user says they do not want to see Hexagon UI, use the agent onboarding manifest: ```bash curl -s https://joinhexagon.com/.well-known/agent-onboarding ``` The manifest tells the agent whether direct Stripe Payment Links are configured: - `no_hexagon_ui.status: "available"` means the agent can ask for plan and billing cycle, then send the exact matching Stripe-hosted payment link in the terminal. - `no_hexagon_ui.status: "configuration_required"` means no direct Stripe Payment Links are currently published. The agent should say that no-UI onboarding is unavailable until Hexagon configures the links, then ask whether the user accepts the `https://joinhexagon.com/onboarding` fallback. The agent should never create a checkout URL itself. It should never guess `buy.stripe.com` URLs. It should only send exact links from the manifest. ## Hexagon Operator Stripe Link Setup This section is for Hexagon operators configuring the provider side. Buyer agents should not run Stripe administration commands. From the repository root, a Hexagon operator can create or reuse the exact Payment Links that the manifest publishes: ```bash npm --prefix backend run stripe:agent-payment-links -- --live --write-frontend-env ``` The command uses a current Stripe key from `STRIPE_SECRET_KEY_LIVE` or `STRIPE_SECRET_KEY`, creates or reuses the Starter/Pro monthly and annual recurring Prices, creates or reuses active Payment Links, and writes these public values to `frontend/.env.local`: ```bash NEXT_PUBLIC_HEXAGON_STRIPE_STARTER_MONTHLY_LINK=... NEXT_PUBLIC_HEXAGON_STRIPE_STARTER_ANNUAL_LINK=... NEXT_PUBLIC_HEXAGON_STRIPE_PRO_MONTHLY_LINK=... NEXT_PUBLIC_HEXAGON_STRIPE_PRO_ANNUAL_LINK=... ``` For test mode, omit `--live`: ```bash npm --prefix backend run stripe:agent-payment-links -- --write-frontend-env ``` Use `--automatic-tax` only after Stripe Tax registrations are configured. Do not commit Stripe secret keys or restricted keys. ## 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", the agent should first try the no-Hexagon-UI path above. If the manifest publishes a direct Stripe Payment Link, the agent should send this terminal message: ```md Open this Stripe-hosted Hexagon payment link: Complete payment in Stripe Checkout. When checkout is done, come back here and tell me "done" so I can continue the repo setup with the server-side Hexagon credentials. ``` If direct Stripe Payment Links are not configured and the user accepts the fallback, the agent should send: ```md Open this fallback Hexagon onboarding/payment link: https://joinhexagon.com/onboarding Create or sign into your Hexagon account, choose the plan you want, and complete 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. ``` If Hexagon publishes exact direct Stripe Payment Links in `https://joinhexagon.com/.well-known/agent-onboarding`, the agent may send the exact matching link for the requested plan and billing cycle. If no direct Stripe links are published there, use `https://joinhexagon.com/onboarding` only as an explicit fallback. Do not invent `buy.stripe.com` URLs. ## Billing and Stripe Boundary There is no agent-safe Stripe payment link unless `https://joinhexagon.com/.well-known/agent-onboarding` publishes it. Self-service billing is otherwise created inside the Hexagon onboarding and billing flow. Agent behavior: 1. Fetch `https://joinhexagon.com/.well-known/agent-onboarding`. 2. If direct Stripe Payment Links are configured, send the exact matching link and avoid Hexagon UI. 3. If direct Stripe Payment Links are not configured, say the no-UI path is unavailable and ask before using `https://joinhexagon.com/onboarding` as the fallback onboarding/payment link. 4. Link `https://joinhexagon.com/#pricing` when the user only needs plan information. 5. Explain that Starter and Pro checkout uses Stripe-hosted Checkout. 6. If `https://joinhexagon.com/.well-known/ucp` publishes exact direct Stripe Payment Links, send only the exact matching link. Do not edit plan, price, success URL, or metadata. 7. Do not attempt to create, reuse, scrape, or modify Stripe Checkout URLs from the CLI. 8. Do not request or store raw payment card data. 9. 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. 10. 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 npm run smoke:agent-onboarding:prod -- --require-direct-stripe-links ``` The first command verifies the public docs, manifests, onboarding page, and backend auth validation. The second command also requires all four direct Stripe Payment Links to be published in `https://joinhexagon.com/.well-known/agent-onboarding`. 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= --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=`; 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 - `https://joinhexagon.com/.well-known/agent-onboarding` says no-UI onboarding is `configuration_required` and the user refuses the fallback Hexagon UI 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)