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.
What the tree holds
Section titled “What the tree holds”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.
key: blog_postkind: collectionname_singular: Blog Postname_plural: Blog Poststitle_field: titleis_active: truefields: - key: title name: Title type: text required: true - key: slug name: Slug type: text - key: body name: Body type: rich_textThe 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:
key: blog_writername: Blog Writergrants: - key: content:entries:read content_model_key: blog_post - key: content:entries:update content_model_key: blog_post - key: content:media:readRoles 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.
Export and import in the console
Section titled “Export and import in the console”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”.
Sync with the CLI
Section titled “Sync with the CLI”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:
npm install --save-dev @plenary/clinpx plenary init --base-url https://your-instance.plenarycms.io --site marketingplenary 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:
npx plenary metadata pull # write every model, form, role, and site you can readnpx plenary metadata diff # show what push would change; writes nothingnpx plenary metadata push # create and update to match the treediff and push print a plan:
create collection docs_noteupdate 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:
npx plenary metadata push --only models,formsDeleting with --prune
Section titled “Deleting with --prune”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.
npx plenary metadata diff --prune # preview the deletesnpx plenary metadata push --prune # asks before deleting; -y to skip the questionCredentials
Section titled “Credentials”| 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.
Promote between environments
Section titled “Promote between environments”Because files use keys, one tree applies to every instance. A typical flow:
- Change models on your local or development instance in the console.
- Run
npx plenary metadata pullagainst that instance and commit the changed files. - Open a pull request. CI runs
npx plenary metadata diffagainst staging so reviewers see the plan. - On merge, CI runs
npx plenary metadata pushagainst 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.
Run in CI
Section titled “Run in CI”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:
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,formsplenary 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.
Related
Section titled “Related”- Model YAML reference: every key in a model file.
- CLI reference: every command and flag.
- Content Models: designing models in the console.
- API Keys: creating the key CI uses.