Copy page

CLI

Shape with CLI

Shape means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without publishing. You preview with apitogo run.

Requires the apitogo CLI (@lukoweb/apitogo). If you have not installed it yet, see Install the CLI.

Happy path

apitogo init creates a project in the current folder: it writes apitogo.config.json, uses an existing docs/ folder, and installs the CLI. Then shape it with apitogo config:

Code
apitogo init
apitogo config         # backend, OpenAPI, pages, plans (apply each immediately)
apitogo run            # http://localhost:3000

Named folder:

Code
apitogo init ./my-portal --name "Books API"
cd ./my-portal
apitogo config
apitogo run

apitogo init does not call the platform. Run apitogo deploy when you are ready to go live.

Interactive config (apitogo config)

On a TTY, bare apitogo config opens the wizard. Each choice is written immediately; the loop continues until you type done:

Choice	What it does
backend	Set gateway.origin: API code folder, runtime and runtime version
openapi	Add an OpenAPI file to gateway.specs
page	Create the React page apitogo/portal/pages/<slug>.tsx (the sidebar follows the files)
plan	Add a plan to apitogo/plans.json (title, price, rate limit, quota)

Fonts and colors are not prompted. See Colors & theme.

Paid plans: payments go through Stripe. Once a plan has a price, apitogo deploy asks for your Stripe secret key (if the project has none yet) and stores it as a project secret. Free and contact-us plans need no key. Set up Stripe for paid plans shows where to find the key and how to add the webhook, with pictures. Paid plans also need Starter or Professional platform hosting; Free cannot publish paid gateway plans or custom domains.

Full reference: Make config (CLI) · Gateway plans

Configure with flags

Changes a config version 2 project. Every change to apitogo.config.json is checked before it is written. The command does not create a project: use init or create for that.

Code
apitogo config --title "Books API"
apitogo config --page-slug guides/quickstart --page-title "Quickstart"
apitogo config --plan '{"sku":"free","displayName":"Free"}'
apitogo config --no-interactive

Common flags:

Flag	Purpose
--interactive / -i	Force wizard (default on TTY). --no-interactive skips it
--title	Set portal.name
--source, --runtime, --runtime-version	Set gateway.origin
--openapi	Add a file to gateway.specs
--page-slug, --page-title	Add a docs page
--plan	Add or replace a plan in plans.json
--patch	Deep-merge JSON into apitogo.config.json

Shape by editing files

After apitogo config, edit the manifest and site files directly:

• Services, backend, OpenAPI files — apitogo.config.json
• Plans — apitogo/plans.json
• Docs pages — the files portal.docs.content names, by default apitogo/portal/pages/**/*.{md,mdx,tsx} (.tsx files are React pages)
• Home page — the file in portal.landing (for example apitogo/portal/landing/LandingPage.tsx)
• Footer — the file in portal.footer (for example apitogo/portal/footer/Footer.tsx). It is shown under every page except the console's (/account, /login, /signup). Remove portal.footer to have none.
• Colors — apitogo/portal/theme.json (or the file in portal.theme). See Colors & theme.
• Logo — portal.logo, an image in apitogo/portal/public/ or an https:// address

apitogo.config.json
{
  "portal": {
    "landing": "apitogo/portal/landing/LandingPage.tsx",
    "footer": "apitogo/portal/footer/Footer.tsx",
    "logo": {
      "light": "apitogo/portal/public/logo.svg",
      "dark": "apitogo/portal/public/logo-dark.svg"
    },
    "docs": { "content": ["apitogo/portal/pages/**/*.{md,mdx}"] }
  }
}

"logo": "apitogo/portal/public/logo.svg" uses one image for both color schemes. Without a logo the header shows portal.name.

Order of the docs pages

The sidebar lists a folder's index page first, then pages with an order, lowest first, then the rest (introduction, getting started and overview before the others, then by name). Set the order in the page itself:

apitogo/portal/pages/authentication.md
---
title: Authentication
order: 2
---

In a React page: export const order = 2;.

When the portal has a home page, / shows it, and an index page of the docs stays at /index.

What the pricing cards show

Each card in apitogo/plans.json lists, in this order:

1. The plan's limits: the rate limit (limits.rateLimit) and the quota (limits.quota)
2. Its own lines, from features
3. The endpoints the plan includes: the ones in includedActions, or every operation of the gateway when the plan names none

apitogo/plans.json
{
  "version": 1,
  "plans": [
    {
      "sku": "pro",
      "displayName": "Pro",
      "priceAmount": 19,
      "priceCurrency": "usd",
      "billingInterval": "month",
      "limits": { "rateLimit": { "calls": 600, "periodSeconds": 60 } },
      "features": ["Email support", "Usage history"],
      "includedActions": ["get:/api/makes", "get:/api/makes/{makeId}"]
    }
  ]
}

apitogo run shows the same cards as the deployed portal.

Add a portal from scratch

In a project that has no portal yet:

Code
apitogo add portal

It adds portal to apitogo.config.json and writes the files above: introduction.mdx (the starter template adds a home page; blank writes an empty pages/ folder), theme.json and the footer. Docs you already have (a docs/ folder, for example) are used instead of a first page; pass --docs <path> to name them. Files that exist are never overwritten.

Never put secrets in apitogo.config.json: the config names a project secret (secret:NAME), and apitogo secrets set NAME stores the value.

Preview locally

Code
apitogo run
apitogo run --port 4000 --open

Production build check:

Code
apitogo build
apitogo build --preview

Shape-phase edits hot-reload when the dev server is running.

Existing docs + OpenAPI folder

In a folder that already has docs and an OpenAPI file, run init there: it uses the docs/ folder in place, and apitogo config (openapi) adds the OpenAPI file:

Code
apitogo init
apitogo config
apitogo run

Next

When the site looks right, go live with apitogo deploy.