Skip to content

Models as Code

Plenary can export its configuration as a tree of YAML files and apply that tree back to any instance. Commit the tree to your site’s repository and your content models change through pull requests, like the code that renders them. The same files move a model from a local instance to staging to production, because every file names things by key, never by an internal id.

The tree lives in a metadata directory, plenary/ at your project root by default, with one file per entity:

plenary/
├── models/
│ ├── blog_post.yaml
│ ├── page.yaml
│ └── obj_seo.yaml
├── forms/
│ └── contact.yaml
├── roles/
│ ├── admin.yaml
│ └── blog_writer.yaml
└── sites/
└── marketing.yaml
Directory Holds Includes
models/ Collections, singletons, and objects Fields, model settings, preview URL, transformers, and relationship names
forms/ Forms Fields and form settings
roles/ The site’s roles Grants, with model filters named by key
sites/ Sites Name, active flag, default locale, locales, timezone, config

The tree does not include:

  • Webhooks, because they carry signing secrets, or a form’s email notifications. An import leaves both untouched on the instance, so pushing a model file never removes its webhooks.
  • Content: entries, form entries, media, users, and API keys.
  • Instance settings (email, SMS, storage) and the license.
  • The permission catalog and the built-in email templates, which come from the Plenary release itself.

A model file looks like this. The full schema is in the Model YAML reference.

plenary/models/blog_post.yaml
key: blog_post
kind: collection
name_singular: Blog Post
name_plural: Blog Posts
title_field: title
is_active: true
fields:
- key: title
name: Title
type: text
required: true
- key: slug
name: Slug
type: text
- key: body
name: Body
type: rich_text

The file has no site_key. A model belongs to exactly one site, and a tree pulled with a site configured (as plenary init --site marketing sets up below) is that site’s tree, so every model in it belongs to marketing. A tree for the whole instance, pulled with --all-sites, writes site_key in each file instead. See Site.

A role file names grants by capability and model key. A role belongs to one site, like a model, so in a site’s tree the file carries no site_key and its grants reach that site only. A grant may still name site_key, but only the role’s own site:

plenary/roles/blog_writer.yaml
key: blog_writer
name: Blog Writer
grants:
- key: content:entries:read
content_model_key: blog_post
- key: content:entries:update
content_model_key: blog_post
- key: content:media:read

Roles travel only in a site’s tree, and only a super user can pull or push them. An instance-wide tree (--all-sites) holds no roles, because every site has its own admin.

The console handles models and forms.

Export every model and form. Go to Content Management → Content, open the YAML menu, and choose Export all to directory…. In browsers without folder access, the item is Export all as zip. Files already in the folder that the export did not write are listed and left in place.

Export one model. Open the model and click Export YAML.

Import. On Content Management → Content, open the YAML menu and choose Import from directory… (pick the metadata directory) or Import files…. Plenary shows a preview of what will be created, updated, or left unchanged, with added (+), changed (~), and removed (−) fields. Click Apply to make the changes. To replace one model from a file, open the model and click Import YAML.

Console imports never delete. A model on the instance that is missing from the files is listed as “left unchanged”.

The @plenary/cli metadata commands move the whole tree, including roles and sites, and can delete what the tree no longer contains.

Set up the project once:

Terminal window
npm install --save-dev @plenary/cli
npx plenary init --base-url https://your-instance.plenarycms.io --site marketing

plenary init writes a plenary.json with the instance URL, site, locale, and metadata directory. It never holds a credential, so commit it.

Then pull, edit, preview, and push:

Terminal window
npx plenary metadata pull # write every model, form, role, and site you can read
npx plenary metadata diff # show what push would change; writes nothing
npx plenary metadata push # create and update to match the tree

diff and push print a plan:

create collection docs_note
update collection post (settings)
update collection student (+info_link ~accent_color)
skipped role marketing/admin (system-owned)
Plan: 1 to create, 2 to update, 1 skipped, 25 unchanged.

+ is a field added, - a field removed, ~ a field changed. settings means a model attribute changed and transformers means a script changed. System roles (admin, developer, editor, reviewer) are never changed and always show as skipped. Add --verbose to list unchanged entities too.

Limit any command to some kinds with --only:

Terminal window
npx plenary metadata push --only models,forms

push never deletes unless you pass --prune. With it, Plenary deletes entities that exist on the instance but not in the tree, only within the kinds the tree contains. A tree with no roles/ directory cannot delete a role, and --only models prunes only models.

Terminal window
npx plenary metadata diff --prune # preview the deletes
npx plenary metadata push --prune # asks before deleting; -y to skip the question
Kinds Credential Grants needed
models, forms A private API key (PLENARY_CLI_API_KEY) or a user session content:models:read, content:models:create, content:models:update, content:forms:read, content:forms:create, content:forms:update; content:transformers:manage for files with transformers; the matching delete capability to prune
roles, sites A user session from plenary login Roles, and creating or deleting a site, need a super user. Updating a site needs admin:sites:update on it. API keys can do neither.

When PLENARY_CLI_API_KEY is set the CLI uses the key even if you are logged in, so to sync roles and sites, run without the key. A key-only run pulls and pushes models and forms and names the kinds it could not read on stderr. If the credential may not make a change, the push is refused as a whole with 403 permission_denied naming the entities, and nothing is written. An invalid file is 422 metadata_invalid with its path.

Because files use keys, one tree applies to every instance. A typical flow:

  1. Change models on your local or development instance in the console.
  2. Run npx plenary metadata pull against that instance and commit the changed files.
  3. Open a pull request. CI runs npx plenary metadata diff against staging so reviewers see the plan.
  4. On merge, CI runs npx plenary metadata push against staging, then production.

Point the CLI at each environment with PLENARY_BASE_URL and PLENARY_CLI_API_KEY; environment variables override plenary.json.

Avoid editing models directly in production once you manage them as code. The next push from the repository overwrites the change.

Give each environment a private API key with the model and form grants listed above, and store it as a CI secret. This GitHub Actions workflow previews changes on pull requests and applies them on main:

.github/workflows/plenary-models.yml
name: Plenary models
on:
pull_request:
paths: ["plenary/**"]
push:
branches: [main]
paths: ["plenary/**"]
jobs:
sync:
runs-on: ubuntu-latest
env:
PLENARY_BASE_URL: ${{ vars.PLENARY_BASE_URL }}
PLENARY_CLI_API_KEY: ${{ secrets.PLENARY_MODELS_KEY }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx plenary status
- name: Preview
if: github.event_name == 'pull_request'
run: npx plenary metadata diff --only models,forms
- name: Apply
if: github.event_name == 'push'
run: npx plenary metadata push --only models,forms

plenary status exits with code 1 when the instance is unreachable or the key is refused, so the job fails before it tries to sync. The workflow passes --only models,forms because an API key cannot push roles or sites. To manage roles and sites from CI too, run those kinds from a job that holds a user session, or apply them by hand with plenary login.