Raytha CLI: install and manage a whole site from the terminal

The raytha command line tool manages a Raytha site through its REST API: themes as plain files, content types and items, site pages and widgets, menus, media, users and functions. Every command prints one JSON document, exit codes are stable, and every error says how to fix it. That makes it a good tool for a developer in a terminal, and a very good tool to hand to an AI agent. This page gets it installed and connected; Build a site with an AI agent shows the workflow the tool was designed for.

Install

Linux and macOS:

curl -fsSL https://raytha.com/cli/install.sh | sh

Windows (PowerShell):

irm https://raytha.com/cli/install.ps1 | iex

The script downloads the release for your operating system and CPU, checks its SHA-256 against the release's SHA256SUMS, and puts a single binary in ~/.local/bin (or %LOCALAPPDATA%\raytha\bin on Windows). If that directory is not on your PATH the script prints the line to add. Set RAYTHA_INSTALL_DIR to install somewhere else, or pass --version vX.Y.Z to pin a release. Both addresses redirect to the installers attached to the latest GitHub release, so you can also fetch those directly.

Builds are static on Linux (musl), so they run on any distribution and in minimal containers, and there are native builds for Intel and Apple silicon Macs. To upgrade, run the install command again. To build from source you need Rust 1.88 or newer:

git clone https://github.com/RaythaHQ/raytha-cli
cd raytha-cli
cargo install --path .

Connect it to a site

The tool needs two values: the site's address and an administrator's API key. Create the key in the admin under Admins, open your account, and select Create API key (see API authentication). The key carries exactly the permissions of the administrator who owns it.

export RAYTHA_URL=https://your-site.example.com
export RAYTHA_API_KEY=your-key
raytha doctor

raytha doctor checks that the address answers, that the key is accepted, and which groups of commands the key may use:

{
  "ok": true,
  "data": {
    "url": "https://your-site.example.com",
    "reachable": true,
    "authenticated": true,
    "version": "2.0.0",
    "organizationName": "Example",
    "cliVersion": "0.1.0",
    "permissions": {
      "templates": true,
      "sitePages": true,
      "contentTypes": true,
      "media": true,
      "users": true
    }
  }
}

The two variables can also be passed as --url and --api-key on any command. Nothing is stored on disk: no config file, no cached key.

The output contract

Standard output is always exactly one JSON document. A success looks like {"ok":true,"data":...}. A failure looks like this:

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "The API key may not manage templates.",
    "hint": "Ask an administrator to grant the Manage Templates permission to the admin this key belongs to.",
    "status": 403
  }
}

Read ok, then error.code and error.hint. Validation errors also carry error.fields with the field names the server rejected. Two commands print something other than JSON: raytha guide prints Markdown and --help prints text. Add --pretty to indent the JSON; leave it off in scripts and pipe through jq.

Exit code	Meaning	What to do
`0`	Success
`2`	Usage or configuration	Fix the command line or set `RAYTHA_URL` and `RAYTHA_API_KEY`. Nothing reached the server.
`3`	Authentication or permission	The key is wrong, or its administrator lacks a permission. The hint names it. Do not work around it.
`4`	Not found	Check the developer name or id.
`5`	Validation	The server rejected the input; `error.fields` says which part.
`6`	Server or network	Reads are safe to retry. Inspect before retrying a write.

Built-in guides

The documentation ships inside the binary, so it always matches the installed version. raytha guide lists the topics and raytha guide <topic> prints one:

overview        How the CLI behaves, output contract, exit codes, command map
build-a-site    End-to-end recipe: theme, content model, pages, menus, go live
themes          Theme directory layout, pull/push workflow, media
liquid          Liquid templating in Raytha: layouts, variables, filters, patterns
widgets         Widget templates, field definitions, and placing widgets on pages
content-types   Modelling content: content types, fields, views, content items
site-pages      Site pages, sections, widgets, draft vs published, home page
media           Uploading and referencing images and files
functions       Raytha Functions: JavaScript for HTTP requests, Liquid and content events
errors          Error codes, what they mean, and how to recover

An agent that has the tool installed therefore has the manual as well. raytha guide build-a-site is the one to read first.

Conventions

Developer names first. Themes, content types, templates and menus are addressed by developer name (my_theme, posts). Site pages and content items are addressed by id.
Edits are partial. Flags you leave out keep their current value. The tool reads the object, merges, and writes it back.
Destructive commands need --yes. delete and purge refuse to run without it.
Dry runs. theme push --dry-run reports what would change and parses every template on the server, so syntax errors show up with a line and column before anything is written. schema import --dry-run does the same for the content model.
Long input from files. Flags that take JSON accept inline JSON, @path, or - for standard input.
Lists page. List commands return items, totalCount and hasMore; --all fetches every page.
Drafts. Site pages and content have a draft and a published version. Commands say whether they publish; --publish does both in one step.

A typical session

raytha doctor
raytha theme pull raytha_default_theme ./site        # the default theme as plain files
# edit site/theme.json, site/web-templates/*.liquid, site/widget-templates/*
raytha theme push ./site --dry-run
raytha theme push ./site --activate

raytha content-type create posts --label-plural Posts --label-singular Post
raytha content create posts --data '{"title":"Hello","content":"<p>First post</p>"}'

raytha site-page create --title About --template raytha_html_page_fullwidth --route-path about \
  --sections '{"main":[{"widgetType":"hero","settings":{"headline":"About us"}}]}'
raytha menu items create main --label About --link /about

raytha check                                          # request every public route, exit 6 if any fail

Themes are the part most people reach for first: pull one into a directory, keep it in git, edit with any editor, and push. Themes and the command line tool covers the directory layout and the sidecar files in detail.

Gotchas

The key inherits its administrator's permissions. If raytha doctor shows a group as false, grant the permission to that administrator or use another key. Nothing in the tool bypasses a 403.
theme pull overwrites local files. Pull into a fresh directory or commit first.
A site page's template must belong to the active theme.
Liquid runtime errors only appear when a page renders. After a push, fetch the public page (or run raytha check) and read the HTML.
When no command covers something, raytha spec --summary lists every operation in the site's OpenAPI document. Paths and methods there are reliable; request body schemas are not.

Next steps

Build a site with an AI agent: the workflow the tool was built for.
Command reference: every command group at a glance.
Themes and the command line tool: themes as directories.
raytha-cli on GitHub: source, releases and issues.