backend/

PROJECT_NAME

Generated by kool create go-react-agent-cli — an agent-driven web app: a Go API server plus a React UI, driven through a CLI with HTTP-verb sub-commands.

Usage

The CLI is a sub-command tree:

go run ./cmd/__PROJECT_NAME__ server     # start the web UI + API (first free port from 8080)
go run ./cmd/__PROJECT_NAME__ get /ping  # GET  - print the response body
go run ./cmd/__PROJECT_NAME__ post /api/counter              # allocate the next id
go run ./cmd/__PROJECT_NAME__ put <URI> '<json>' --json      # replace a resource
go run ./cmd/__PROJECT_NAME__ delete <URI>                   # delete a resource
go run ./cmd/__PROJECT_NAME__ skill --show                   # the __PROJECT_NAME__ agent skill

URIs are bare paths (/api/counter → http://localhost:8080) or full URLs. Writes are silent on success; --json prints the response body; --dry-run prints the request without sending it. Install the agent skill with go run ./cmd/__PROJECT_NAME__ skill --install.

To mount the app under a sub-route, pass --route-prefix:

go run ./cmd/__PROJECT_NAME__ server --route-prefix my-app

Then open http://localhost:<port>/my-app/.

API

Unknown /api/* paths return a JSON 404 (not the UI page), so CLI and agent callers always get machine-readable errors. Register new routes in server/server.go (RegisterAPI); the counter in server/store.go shows the persistent-state pattern (~/.<project>/id.json via the shared id allocator):

go run ./cmd/__PROJECT_NAME__ post /api/counter   # silent, allocates the next id
go run ./cmd/__PROJECT_NAME__ get /api/counter --json   # {"last":1}
go run ./cmd/__PROJECT_NAME__ get /api/pages/home --json # cards with meta + rows

Ids are sequential, survive restarts, and are safe across processes. Replace the counter with your own storage when you no longer need it.

Cards carry server-owned meta (server/pagemeta/parts/<Card>.json: title, hint, empty). /api/pages/home returns the page document — cards in web order, each with meta, an empty flag and its rows — so an agent reading the API learns what every card is for without opening a .tsx. The React card imports the same part over the @pagemeta/ alias.

Agent skill

skill/SKILL.md is embedded in the binary and teaches agents the whole workflow. Show it with go run ./cmd/__PROJECT_NAME__ skill --show, install it with go run ./cmd/__PROJECT_NAME__ skill --install (lands in ~/.agents/skills/__PROJECT_NAME__).

Development

Dev Mode (recommended)

Starts Vite (HMR) and rebuilds the Go API with air on .go changes:

go run ./script/dev

Options:

go run ./script/dev --port 9000
go run ./script/dev --route-prefix my-app # serves http://localhost:<port>/my-app/
go run ./script/dev --no-air          # compatibility alias: no backend hot reload
go run ./script/dev --no-open

Plain in-process Vite (no air) is still available:

go run ./script/dev --external-vite --vite-port 5173

External React Source

The generated frontend includes an external_src/ directory next to src/. Code in that directory can be imported with the @external_src alias:

import { ExternalDemo } from '@external_src/demo-external/frontend/src/ExternalDemo';

Release Mode (Production Build)

1. Build the frontend (embeds __PROJECT_NAME__-react/dist):

go run ./script/build-frontend

1. Run the server (embeds the built frontend):

go run ./cmd/__PROJECT_NAME__ server

Build / Install

go run ./script/build-frontend && go run ./script/build
go run ./script/install