cli workflow.md

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

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:

What Requires User Action

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

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:

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

The manifest tells the agent whether direct Stripe Payment Links are configured:

To select the Pro monthly link from the terminal:

curl -s https://joinhexagon.com/.well-known/agent-onboarding | jq -r --arg plan_cycle pro_monthly '.payment.direct_stripe_payment_links.by_plan_cycle[$plan_cycle].url // empty'

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:

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:

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:

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:

Open this Stripe-hosted Hexagon payment link:
<exact Stripe Payment Link from payment.direct_stripe_payment_links.by_plan_cycle[plan_cycle].url>

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:

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. Ask the user for one plan cycle: starter_monthly, starter_annual, pro_monthly, or pro_annual.
  3. If payment.direct_stripe_payment_links.by_plan_cycle[plan_cycle].url exists, send that exact link and avoid Hexagon UI.
  4. If the requested plan cycle is missing, say the no-UI path is unavailable for that plan cycle and ask before using https://joinhexagon.com/onboarding as the fallback onboarding/payment link.
  5. Link https://joinhexagon.com/#pricing when the user only needs plan information.
  6. Explain that Starter and Pro checkout uses Stripe-hosted Checkout.
  7. 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.
  8. Do not attempt to create, reuse, scrape, or modify Stripe Checkout URLs from the CLI.
  9. Do not request or store raw payment card data.
  10. 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.
  11. 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:

export HEXAGON_MERCHANT_ID="..."
export HEXAGON_API_KEY="..."

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

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:

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:

npm test
npm run lint
npm run build

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

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:

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:

Related Docs