Total CMS

View saved version →

---
name: totalcms
description: Use when building, editing, or managing a Total CMS (T3) site — Site Builder pages and SEO, collections, schemas and field choice, objects and imports, forms and public registration, access groups, automations, Data Views, search, feeds, the MCP server, the tcms CLI, the frontend/Vite pipeline, push/pull to production, writing a T3 extension, or troubleshooting a problem and reporting a Total CMS bug. Covers the local build workflow end to end.
---

# Building a Total CMS (T3) site

This project **is a website** built on Total CMS, a flat-file PHP CMS. There is
**no database** — all content is JSON under `tcms-data/`. Configure via
`config/tcms.php` (deep-merged — specify only keys you change).

## Is this copy current?

This check applies only inside a Total CMS project. If you are not working in
one — this skill came with a plugin and the current folder has no Total CMS CLI
— skip it: there is no installed copy to check, and this text describes the
latest release. When a project's own copy (in `.claude/skills/totalcms/`) is
also loaded, follow that one: it matches the CMS version the project runs.

In a project, this skill is a copy of the one shipped with the installed CMS, so
it can fall behind. At the start of a session run `vendor/bin/tcms skill:install --check`.
If it reports stale, run `vendor/bin/tcms skill:install` and then tell the user
to start a new session — the text already loaded cannot replace itself. The
stamp is a hash of the skill's own content, not the release number, so only real
changes to the skill flag it.

## Where things are

T3 ships in two layouts. Check which one you are in before running anything.

- **Composer install** — the default the rest of this skill assumes. CLI `vendor/bin/tcms`; CMS code and docs under `vendor/totalcms/cms/`; config `config/tcms.php` at the project root. **Never edit `vendor/`** — an update replaces it. <!-- composer-paths -->
- **Zip install** — the CMS *is* the folder you are in (conventionally `tcms/`).
  CLI `php resources/bin/tcms`, run from that folder; docs `resources/docs/`;
  config `config/tcms.php` inside it; content in `../tcms-data/` beside it. An
  update replaces the folder's `config/ public/ resources/ src/ vendor/`
  wholesale, so **never add files inside them**.

If this skill was installed by `skill:install` on a zip install, the paths
throughout it are already rewritten for that layout.

Most commands accept `--json` for machine-readable output — prefer it when
scripting. Run `vendor/bin/tcms list` to see everything.

## Write through the CLI, never to the files

`tcms-data/` is a store, not an editing surface. It is tempting to create or
edit the JSON files in it directly — it usually appears to work, which is what
makes it dangerous. **Always go through the CLI (or the API/MCP), which is what
the admin does:**

| To… | Run |
|---|---|
| create an object | `vendor/bin/tcms object:create <collection> -` (JSON on stdin) |
| change part of an object | `vendor/bin/tcms object:patch <collection> <id> -` |
| load many objects | `vendor/bin/tcms collection:import <collection> file.json` |
| add or change a schema | `vendor/bin/tcms schema:import schema.json`, then `schema:lint <id> --strict` |
| create a collection | `vendor/bin/tcms collection:create …` |
| change a collection's settings | `vendor/bin/tcms collection:update <id> --set ownerProperty=author` (or JSON on stdin) |
| add or change an access group | `vendor/bin/tcms access-group:set <id> -` / `access-group:patch <id> -` |
| seed structure + content together | `vendor/bin/tcms jumpstart:import file.json` |

**Mailer templates, automations and Data Views are collections too**
(`mailer`, `automations`, `dataviews`), so the same `object:*` commands read and
change them: `vendor/bin/tcms object:patch mailer <id> -` edits one mailer field
and leaves the rest. Run `vendor/bin/tcms collection:list` to see every
collection, the reserved ones included, before deciding that

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.