Build a site with an AI agent

Raytha treats AI agents as first-class builders. The raytha CLI speaks JSON, carries its own manual, dry-runs changes, and checks the finished site, which is exactly what an agent needs to go from "build me a site for a pottery studio" to a live theme, content model, seed content, pages and navigation without a human clicking through the admin. This page shows how to set that up with Cursor, Claude Code, Codex or any agent that can run shell commands, and how to review what it built.

What the agent gets

An agent is only as good as the tools and feedback it has. The CLI gives it:

• One JSON document per command, with ok, data or error. No screen scraping, no guessing whether a call worked.
• Errors that say what to do. Every failure has a code and a hint. Validation errors name the field. Liquid syntax errors come back with a line and column.
• The manual inside the binary. raytha guide build-a-site is the end-to-end recipe; themes, liquid, widgets, content-types, site-pages, media, functions and errors cover the rest. The docs match the installed version, so the agent reads them instead of remembering an older API.
• Files, not forms. raytha theme pull turns a theme into a directory of Liquid and JSON. The agent edits files, keeps them in git, and pushes.
• Dry runs. theme push --dry-run parses every template on the server before writing. schema import --dry-run does the same for the content model.
• A finish line. raytha check requests every public route and exits non-zero if any fail, so the agent knows when it is done and what is still broken.

1. Have a Raytha site

The agent builds into a running site. Deploy on Railway (recommended, PostgreSQL included) or run the Docker image; the quickstart covers both. Finish the setup screen so the first administrator exists. A fresh install is the ideal starting point: the agent gets the default theme to copy and a sample posts type it can keep or delete.

2. Create an API key for the agent

In the admin, open Admins, open the account the agent should act as, and select Create API key. The key has that administrator's permissions and nothing more, which is the control you have over the agent: give it an administrator whose role can manage templates, content types, site pages and media, and leave out system settings or users if the task does not need them. raytha doctor shows the agent which groups it may use, and the CLI's own instructions tell it to stop and report a missing permission rather than work around it.

3. Install the CLI where the agent runs

curl -fsSL https://raytha.com/cli/install.sh | sh
export RAYTHA_URL=https://your-site.example.com
export RAYTHA_API_KEY=your-key
raytha doctor

Run this in the shell the agent uses: your machine for Cursor or Claude Code, the container for a cloud agent or CI. On Windows use irm https://raytha.com/cli/install.ps1 | iex. See The Raytha CLI for the details.

4. Give the agent the rules

The raytha-cli repository ships a short skill file, skills/raytha/SKILL.md, in the Agent Skills format that Cursor and Claude Code read from a skills directory. Copy it into your project (for example .cursor/skills/raytha/SKILL.md or .claude/skills/raytha/SKILL.md), or paste the same rules into the project's AGENTS.md:

## Using the raytha CLI

1. `raytha doctor` first. It checks the URL, the key, and which command groups the key may use.
2. `raytha guide` lists the docs; read `raytha guide build-a-site` before touching anything, then
   `themes`, `liquid`, `widgets`, `site-pages`, `content-types` as needed. `errors` explains every failure.
3. Work from files. `raytha theme pull raytha_default_theme ./site`, edit, `raytha theme push ./site --dry-run`,
   then push for real. Keep the directory in git.
4. Read `ok`, `error.code` and `error.hint` in the JSON; exit codes: 2 usage, 3 auth, 4 not found,
   5 validation, 6 server. Never guess around a `forbidden`; tell the user which permission is missing.
5. After a change, fetch the public page (`curl -s "$RAYTHA_URL/path"`) and look at the HTML.
   Liquid errors only show up at render time.

Configuration is two environment variables: `RAYTHA_URL` and `RAYTHA_API_KEY`.

Those five rules are the whole protocol. The rest of what the agent needs is in raytha guide.

5. Write the prompt

Describe the site the way you would brief a contractor: who it is for, what it contains, how it should feel, and what done means. A prompt that one-shots a complete site looks like this:

You have the `raytha` CLI installed and RAYTHA_URL and RAYTHA_API_KEY set. Run `raytha doctor`,
then read `raytha guide build-a-site` and follow it.

Build a complete website for Kiln & Kettle, a pottery studio and tea room in a converted mill.
It sells hand-thrown pieces, runs wheel classes and serves tea.

- Theme: pull raytha_default_theme into ./site, rename it `kiln`, and redesign it: warm paper and
  clay colours, a serif display face, one base layout, list and detail templates for each content
  type, and restyled 404 and 500 pages. Push with --dry-run first, then push and activate.
- Content model: makers, pieces (with a maker relationship, price, dimensions, photos, a status
  dropdown), workshops (date, price, level, seats), teas, and a journal. Use the field types that fit.
- Seed content: at least 5 makers, 20 pieces, 8 workshops, 10 teas and 6 journal entries.
  Generate images for pieces and upload them as attachments.
- Site pages: home, the studio, visit (hours and map), classes, custom orders. Build them from widget
  templates you create: hero, feature grid, showcase that renders a view, FAQ, call to action.
- Navigation: a main menu with a dropdown for the shop, and a footer menu.
- Finish with `raytha check` and fix anything it reports. Keep ./site and your seed scripts in git.

Shorter prompts work too. "Build me a photography portfolio with galleries and a contact page" produces a site; the detail above produces the site you had in mind. Hand the agent the brief, let it work, and read the summary it writes at the end.

6. What the agent does

Following raytha guide build-a-site, a run looks like this. Each step is a command whose JSON the agent reads before taking the next one.

1. raytha doctor, then raytha theme list, content-type list, site-page list and menu list to see what exists.
2. raytha theme pull raytha_default_theme ./site, edit theme.json, the base layout, the templates and the widget templates.
3. raytha theme push ./site --dry-run, fix any syntax errors it reports, raytha theme push ./site --activate.
4. raytha content-type create and fields create for each type, or one raytha schema import from a document it wrote.
5. raytha content create or raytha content import for the seed content, with @file: references for images.
6. raytha site-page create for each page with its sections of widgets, raytha menu items create for navigation.
7. curl the public pages and read the HTML, raytha check, fix, repeat until it passes.

Two complete sites built this way, with every command the agent ran, are in the repository under examples/: Aurora Observatory and Kiln & Kettle (five content types, 63 items, 19 widgets, 17 views, six site pages and six functions, on an empty install). They are a good way to calibrate what to ask for.

7. Review what it built

• The site. Open it. raytha check proves every route renders; it does not prove the design is right.
• The files. The theme is in ./site in git. git log and git diff show what changed and why. Push a fix yourself with raytha theme push ./site.
• The audit log. Every write the agent made is in the admin's audit log under the administrator whose key it used (View the audit logs). Content items keep revisions; templates keep revisions.
• Iterate. The next prompt can be small: "make the hero taller and add a newsletter widget to the home page". The agent pulls, edits, dry-runs, pushes.

Working with an existing site

The same setup works on a site that already has content. Point the agent at it and ask for a redesign, a new section, or a content migration. Two commands matter here: raytha theme duplicate current_theme new_theme --wait copies the live theme with every view and item binding so the agent edits a copy, and raytha theme push --dry-run keeps the push honest. Activate the new theme when you have looked at it. raytha theme usage shows what would break before a template is deleted, and --prune is never implied.

Guardrails

• The API key is the permission boundary. Scope the administrator's role to the task.
• Destructive commands require --yes, and the agent's instructions tell it to dry-run pushes. Still, do the first run against a fresh or duplicated site, not production.
• On a 403 the CLI tells the agent which permission is missing and to stop. Do not grant permissions mid-run without reading why.
• Keep the theme directory and seed scripts in a repository. The server is a deploy target; the files are the source.
• Give the agent a way to look. The CLI's instructions include fetching the public page after a change. raytha web-template preview renders a template on the server with real data without publishing.

Next steps

• The Raytha CLI: install, connect, output contract.
• Command reference: every command group.
• Themes and the command line tool: the directory layout the agent edits.
• Example sites: two complete builds to learn from.