@octanest/cli

octanest checks a custom storefront app, signs the developer in, writes .env.local for one storefront, runs that app locally, and deploys it.

Install:

npm i -g @octanest/cli     # then: octanest login
npx @octanest/cli login    # or without installing

It talks to the Octanest dev API (https://dev.apis.octanest.com) by default. Point it elsewhere with --auth-base <url> or OCTANEST_AUTH_BASE_URL.

From the platform repo:

node packages/cli/bin/octanest.js doctor --env templates/next-store/.env.example
node packages/cli/bin/octanest.js login
node packages/cli/bin/octanest.js link --storefront <storefront-id>
node packages/cli/bin/octanest.js dev
node packages/cli/bin/octanest.js deploy --target netlify
node packages/cli/bin/octanest.js deploy --target vercel
node packages/cli/bin/octanest.js deploy --target cloudflare

From an app:

npx octanest doctor
npx octanest doctor --url http://localhost:3000
npx octanest doctor --json
npx octanest login
npx octanest link
npx octanest link --storefront <storefront-id>
npx octanest dev
npx octanest deploy --target vercel
npx octanest deploy --target cloudflare

doctor

Each line is ✓ or ✗. The command exits 0 only when every check passes.

• The env file contains every key from templates/next-store/.env.example (or the app's .env.example).
• Some page calls resolveStorefrontCached or storefronts.resolve.
• Installed @octanest/* versions satisfy the versions in package.json and the same package is not installed twice.
• With --url: GET / is 200, /sitemap.xml and /robots.txt exist, /api/checkout-handoff is not a 5xx, and the OAuth callback route exists. This does not create a checkout.

login

Device-code sign-in against the Octanest OAuth server (OCTANEST_AUTH_BASE_URL, or https://dev.apis.octanest.com/octanest/api).

The command reads /.well-known/oauth-authorization-server when that document is available. It starts the flow at device_authorization_endpoint, or at /oauth2/device_authorization next to the token endpoint, then polls /oauth2/token with urn:ietf:params:oauth:grant-type:device_code.

It prints the user code and the verification URL. On success it writes ~/.octanest/credentials.json (mode 0600). The access token is not printed. Override the file with --credentials.

link

Lists the merchant's storefronts with the same calls the developer tools use: GET /user/merchant/accounts on the Arounds API, then GET /v1/storefronts on the catalog API. With one storefront it writes the env file. With several, pass --storefront.

The file is templates/next-store/.env.local when that template exists, otherwise .env.local beside .env.example. Keys come from the template. STOREFRONT_ID is set, and the API base URLs match get_app_env (OCTANEST_CATALOG_BASE_URL, auth, orders, arounds, and the NEXT_PUBLIC_ copies) when the issuer is known.

If those calls cannot run, octanest link --storefront <id> still writes .env.local from the template example plus that id.

dev

Runs next dev for the current directory when it is a Next.js app, otherwise for templates/next-store.

When cloudflared is on PATH, it starts a Cloudflare quick tunnel (cloudflared tunnel --url http://127.0.0.1:<port>) and registers that https address. Registration uses the same storefront config write as the MCP tool register_app_url: read GET /v1/storefronts/{id}/config, then PUT it with the origin on commerce.returnUrlAllowlist and, for https, customApp.publicUrl. The command then prints the Builder preview link (/preview/{storefrontId}?token=… on that address).

The storefront is the one in the app's .env.local, the only storefront on the account, or --storefront. The token comes from ~/.octanest/credentials.json.

If the app has custom sections, the command uploads them for the Builder. It reads octanest.sections.json and the defineSection side file octanest.sections.mjs (see @octanest/mart-ui). Each entry is sent as app:custom/<id>. When neither file exists, dev continues and does not call the sections API. A failed upload is printed and Next keeps running.

If cloudflared is missing, the command prints how to install it and still runs Next on localhost. If there is no saved token, it prints that you must run octanest login first and still leaves Next running. Ctrl+C stops Next and the tunnel.

deploy

octanest deploy --target vercel or octanest deploy --target cloudflare builds templates/next-store (or the Next app in the current directory) and publishes it.

Vercel uses the Next.js adapter already implied by the template: vercel build --prod, then vercel deploy --prebuilt --prod. Cloudflare uses the template's OpenNext setup (open-next.config.ts and wrangler.jsonc): opennextjs-cloudflare build, then wrangler deploy.

Env comes from ~/.octanest/credentials.json (the API bases for that login) and the app's .env.local (the template file when you run from the repo). Values already set in .env.local stay. The command writes those Octanest values into .env.local for the build, then passes them to the host CLI. If there is no saved login, it exits 1 and prints Run octanest login first.

After the host prints a production URL, the command registers that origin with registerAppUrl, registers the sign-in callback (/api/oauth/callback) through the same helper module, uploads custom sections when octanest.sections.json or octanest.sections.mjs is present, then runs doctor against that URL. A missing sections file is skipped.

octanest deploy --target netlify also shows the deployment in the store's console (Storefront → Custom app → Hosting):

1. Connect Netlify to the store there.
2. The command creates or reuses the store's Netlify site and pushes the env vars the console keeps (platform OCTANEST_* plus your own).
3. It runs netlify deploy --build --prod --site <id> --json with your local netlify login. Netlify's Next.js adapter runs in that build.
4. It reports the deploy, so the console lists it with rollback.

Adapters live in lib/hosting/adapters.mjs. A new host is one adapter with:

• bins: the commands it needs, with install hints
• commands
• result
• optionally, managed with a before step

The Vercel or Cloudflare login is the one already on this machine (vercel login or wrangler login). Those vendor tokens are not written into ~/.octanest/credentials.json. vercel, wrangler, and the OpenNext build run only through one command runner. If vercel or wrangler is missing, the command prints how to install it and exits 1.

Deploy from GitHub (push to deploy)

npx @octanest/cli github workflow --storefront <id> --branch main

This writes .github/workflows/octanest-deploy.yml. Commit it, then on the store's Hosting card connect GitHub and track this repository and branch.

• Push to the branch: deploys to production.
• Pull request into it: deploys a preview, and the workflow comments its URL on the pull request.

The workflow holds no secrets. Each run proves which repository, branch and event it is with GitHub's OIDC token (permissions: id-token: write). Octanest checks that against what the store tracks, then lends the run the store's Netlify credential for that deploy only.

A fork's pull request gets no OIDC token, so it can't deploy. pull_request_target is refused. Netlify only for now.