Skip to content

CLI

@plenary/cli installs the plenary command, a client for the Plenary HTTP API that runs from a terminal, a script, or a CI job. Use it to keep model YAML in step with an instance, automate content and media work, manage API keys, and call any endpoint directly. It works against any instance you hold a credential for, Plenary Cloud included.

Everything the CLI does goes through the API, so it is attributed to your credential, limited by its grants, and recorded in revision history like any other client.

Node.js 20 or later is required.

Terminal window
# In a project (recommended): pinned with your other dependencies
npm install --save-dev @plenary/cli
npx plenary --help
# Or globally
npm install -g @plenary/cli
plenary --help

plenary --version (or -v) prints the installed version.

The CLI needs a base URL (the instance origin, without /api/v1), usually a site key, and a credential. Settings resolve in this order, highest first:

  1. A command-line flag.
  2. A process environment variable.
  3. A .env file next to plenary.json (or in the working directory when there is no plenary.json). Only PLENARY_* lines are read.
  4. plenary.json, found by searching upward from the working directory.

These go before or after the command name and apply to every command.

Flag Environment variable plenary.json key Meaning
--base-url <url> PLENARY_BASE_URL baseUrl Instance URL, such as https://your-instance.plenarycms.io. A trailing / is removed.
--api-key <key> PLENARY_CLI_API_KEY none API key to authenticate content commands with.
--site <key> PLENARY_SITE_KEY siteKey Site key for entry and form-entry commands.
--locale <code> PLENARY_LOCALE locale Locale for entry reads and writes. Defaults to the site’s default locale.
none PLENARY_METADATA_DIR metadataDir Metadata directory for metadata commands. Default plenary, relative to plenary.json.
--config <path> none none Use this plenary.json instead of searching for one. Exits 2 if the file is missing.
--json none none Print machine-readable JSON instead of tables.
--debug none none Print each request (> GET …, < 200) and full stack traces to stderr.
-h, --help none none Help for any command or subcommand.

plenary login also reads PLENARY_USERNAME and PLENARY_PASSWORD, and the session store honors XDG_CONFIG_HOME.

plenary.json
{
"baseUrl": "https://your-instance.plenarycms.io",
"siteKey": "marketing",
"locale": "en-us",
"metadataDir": "plenary"
}

Every key is optional and every value is a string. Any other key, including anything that looks like a credential, is rejected with exit code 2, so the file is safe to commit. plenary init writes it.

There are no named profiles. To work with several instances, keep a plenary.json per project, pass --config, or set PLENARY_BASE_URL and PLENARY_CLI_API_KEY per environment (for example, per CI job).

The CLI uses two kinds of credential for different work.

An API key (PLENARY_CLI_API_KEY or --api-key), sent as X-API-KEY. It can do exactly what its grants allow. API keys hold only content:* capabilities, so a key can sync models and forms and manage entries and media, but cannot reach roles, API keys, or site management. Use a private key for CI and scripts. See API Keys.

The CLI does not read PLENARY_API_KEY, the variable your site uses for its public key. The CLI reads the same .env that frameworks such as Next.js load, so keeping the names apart stops the CLI’s private key from reaching your site’s runtime.

A user session from plenary login. It carries your role, so it reaches admin:* routes. Only the refresh token is stored, in $XDG_CONFIG_HOME/plenary/credentials.json (~/.config/plenary/credentials.json by default), readable only by you and keyed by instance URL. Each run exchanges it for a fresh access token and writes the rotated refresh token back. A session the server refuses is deleted, with a message to log in again.

Which credential a command uses:

Commands Credential
roles, api-keys The user session, even when an API key is configured. These fail with exit code 2 if you are not logged in.
metadata, models, forms, entries, media, sites The API key if one is configured, otherwise the user session.
api The API key if one is configured, otherwise the user session, otherwise no credential.
status The health check needs none; the credential line uses whichever is configured.

Because metadata prefers the key, a run with PLENARY_CLI_API_KEY set syncs models and forms only. To pull or push roles and sites, unset the key and use a session from plenary login. Roles need a super user.

A configured key always wins for content work, so a person’s login never silently becomes the actor of a deploy job that also has a key. plenary whoami shows which credential each kind of command will use.

  • Tables and reports go to stdout. With --json, the API’s JSON response goes to stdout, pretty-printed. export commands write NDJSON, one object per line.

  • Errors go to stderr as plenary: <code> (HTTP <status>), followed by the error’s vars, one per line:

    plenary: api_key_grant_not_allowed (HTTP 422)
    capabilities: ["admin:api_keys:read"]
  • Commands that delete something ask for confirmation on a terminal. Without a terminal they need -y.

Exit code Meaning
0 Success.
1 The API refused the request (any non-2xx response), the instance was unreachable, a file could not be read, or a batch had failures.
2 Usage error: unknown command or flag, malformed flag value, missing base URL, missing credential or site key, a confirmation the run could not ask for, or a 2FA login without a terminal.

Writes plenary.json in the working directory. Values come from --base-url, --site, and --locale (or their environment variables); on a terminal, anything missing is prompted for.

Flag Meaning
--dir <path> Metadata directory, relative to the config file. Default plenary.
-f, --force Overwrite an existing plenary.json.
Terminal window
npx plenary init --base-url https://your-instance.plenarycms.io --site marketing --locale en-us

Signs in as a user and stores the session for this instance.

Flag Meaning
-u, --identifier <email-or-username> Who to sign in as. Defaults to PLENARY_USERNAME, then a prompt.
--otp-method <email|sms> How to receive a two-factor code when more than one method is offered.

The password is never a flag. It is prompted for without echo, or read from PLENARY_PASSWORD when there is no terminal. With two-factor sign-in on the account, the CLI prompts for the code, which needs a terminal.

Terminal window
npx plenary login -u jane@example.com
# logged in to https://your-instance.plenarycms.io as jane@example.com (Admin)

The login endpoint is rate-limited per IP address. Log in once and let the stored session refresh itself.

Revokes the stored session on the server and deletes it locally. The local copy is deleted even if the server call fails. Takes no options.

Shows the credentials this run would use and which commands each serves. Takes no options.

API key private "Deploy job" (4 grants), used for content commands
Session jane@example.com (Admin), used for admin commands

Calls GET /api/v1/health and, when a credential is configured, GET /api/v1/auth/me. Takes no options.

Instance https://your-instance.plenarycms.io
Version 1.0.0 (on-prem)
Status ok, database ok, license ok
Credential private API key "Deploy job" (4 grants)
Config /srv/site/plenary.json

Exits 1 when the instance is unreachable or the credential is refused, so it is a good first step in a CI job.

Keeps a directory of YAML files in step with the instance: models/, forms/, roles/, and sites/ under the metadata directory, one <key>.yaml per entity. See Models as Code for the workflow and Model YAML for the file format.

One site’s tree. With a site configured (--site, PLENARY_SITE_KEY, or siteKey in plenary.json, which plenary init writes), pull, diff, and push move that site’s tree only: the models, forms, and object models it owns, its roles, and its own sites/<key>.yaml. Files in a site’s tree carry no site_key. A push may not reach outside the site: a model or role assigned to another site, or another site’s file, fails with 422 metadata_invalid, and --prune deletes only within the site.

The whole instance. --all-sites moves every site’s models, forms, and site files, and each model file carries its site_key. It holds no roles, because every role belongs to a site, so --only roles with --all-sites is refused. While two sites use the same model key, the instance-wide tree cannot tell those models apart: export fails with 422 model_site_key_required, naming the keys in vars.models, and you work one site at a time instead.

Writes every model, form, role, and site the credential may read into the directory. Kinds the credential may not read are named on stderr. Files on disk that the server did not send are listed and left alone.

Flag Meaning
--dir <path> Metadata directory for this run.
--only <kinds> Comma list of models, forms, roles, sites, or all (default).
--all-sites Pull the whole instance instead of the configured site.
wrote 28 files to /srv/site/plenary

Validates the whole directory and prints what push would do, without writing anything.

Flag Meaning
--dir <path> Metadata directory for this run.
--only <kinds> Limit to some kinds.
--all-sites Work on the whole instance instead of the configured site.
--prune Include what push --prune would delete.
--verbose List unchanged entities too.
delete form old_survey
create collection event
update collection post (+subtitle ~title settings)
skipped role marketing/admin (system-owned)
Plan: 1 to create, 1 to update, 1 to delete, 1 skipped, 25 unchanged.

In each detail, + is a field added, ~ a field changed, - a field removed, settings a model attribute changed, and transformers a script changed. With nothing to do it prints No changes: 28 unchanged.

Applies the directory: creates and updates entities to match it, and deletes only with --prune.

Flag Meaning
--dir <path> Metadata directory for this run.
--only <kinds> Limit to some kinds.
--all-sites Work on the whole instance instead of the configured site.
--prune Also delete entities missing from the directory, only within the kinds the directory contains.
-y, --yes Do not ask before pruning. Required for --prune without a terminal.
--dry-run Same as diff.
--verbose List unchanged entities too.
create collection event
Applied: 1 to create, 0 to update, 0 unchanged.

A site’s Admin role is never changed or deleted and is reported as skipped; roles are named <site>/<key> in the plan. A tree with no roles/ directory cannot delete a role. If the credential may not make any one change, the whole push is refused with 403 permission_denied naming the entities, and nothing is written. An invalid file fails with 422 metadata_invalid and its path.

Models and forms work with an API key or a session. Roles and sites need a session from plenary login, with no API key configured for the run.

Command Does
plenary models list Table of every model: key, kind, name, field count, and inactive when applicable.
plenary models get <key> One model by key or id, with its fields.
plenary models get <key> --yaml The model as the YAML file the metadata commands use.
KEY KIND NAME FIELDS
blog_post collection Blog Post 4
obj_address object Address 5
Command Does
plenary forms list Table of every form.
plenary forms get <key> One form by key or id. --yaml prints its YAML file.
plenary forms entries list <form> Table of the form’s entries.
plenary forms entries export <form> Every matching form entry as NDJSON on stdout.

forms entries list and forms entries export take the query flags --where, --filters, --sort, --limit, --offset, and --count. The configured site key, if any, narrows them to that site.

Terminal window
npx plenary forms entries list contact --where status=new --sort created_at:desc
npx plenary forms entries export contact > contact.ndjson
ID STATUS SITE CREATED DATA
59cf3f98-3548-458c-8073-58c26a339b59 read marketing 2026-07-28T16:04:04.902Z email=visitor@example.com first_name=Visitor

Content entries, read through the same query engine as the client SDK. Every entries command needs a site key (--site, PLENARY_SITE_KEY, or siteKey). The locale defaults to the site’s default locale.

Command Does
entries list <model> Table of matching entries: id, status, slug, title, updated time.
entries get <model> [slug-or-id] One entry as JSON. Omit the slug for a singleton.
entries create <model> Create a draft entry.
entries update <model> <slug-or-id> Update an entry, merging --data into its fields. On a published entry the update is saved as pending changes.
entries archive <id> Archive an entry. It keeps its history and can be restored from the console.
entries archived <model> Table of the model’s archived entries, newest first.
entries restore <id> Restore an archived entry as a draft.
entries delete <id> Permanently delete an entry and its history. Cannot be undone.
entries publish <id> Publish an entry now. On a published entry, make its pending changes live.
entries unpublish <id> Unpublish an entry now. --draft merge|discard says what an entry with pending changes keeps.
entries discard <id> Drop a published entry’s pending changes. Takes --note <text>.
entries export <model> Every matching entry as NDJSON on stdout, paging through the whole result.
entries import <model> <file> Create one entry per NDJSON line. <file> may be - for stdin.

Used by entries list, entries export, and (except --include, --exclude, --hydrate) forms entries list|export.

Flag Meaning
-w, --where <field=value> Filter. field=value is equality; field=$op:value uses an operator: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $like, $ilike, $is_null. $in and $nin take a comma list; $is_null takes true or false. Repeatable.
--filters <json> A whole filter tree as JSON: inline, @file, or - for stdin. Cannot be combined with --where.
-s, --sort <field[:dir]> Sort field, ascending unless :desc. Repeatable, in precedence order.
--limit <n> Page size.
--offset <n> Rows to skip.
--count Ask for the total and print N of TOTAL under the table.
--include <fields> Comma-separated data fields to return.
--exclude <fields> Comma-separated data fields to leave out.
--hydrate <field[=subfields]> Hydrate a reference field. Repeatable.

entries get takes --include, --exclude, and --hydrate.

Terminal window
npx plenary entries list blog_post --where status=published --sort updated_at:desc --limit 20 --count
npx plenary entries list blog_post --where 'data.tag=$in:news,events'
npx plenary entries get blog_post hello-world --hydrate data.author
npx plenary entries get site_settings
ID STATUS SLUG TITLE UPDATED
131156b3-48b4-448e-b2d0-1799e5943b3a published hello-world Hello, world 2026-09-20T02:34:42.788Z
1 of 1

Used by entries create and entries update.

Flag Meaning
-d, --data <json> Field values as a JSON object: inline, @file, or - for stdin. Required for create.
--slug <slug> The entry’s slug.
--folder <id> Content folder id.
--folder-path <path> Content folder path, such as /company/team, instead of --folder. / is the root.
--note <text> Revision note. Required by models with Require Change Notes.
--publish-at <iso> Schedule a publish.
--unpublish-at <iso> Schedule an unpublish.
--publish Publish the entry right after writing it, in a second request.

create always makes a draft; --publish publishes it in a second request. update reads the entry first and merges --data into its fields (a null value removes a field), and keeps the slug, locale, folder, and schedule unless a flag changes them. The API’s PUT replaces the whole entry, so the CLI does this round trip for you.

On a published entry, update saves pending changes and the live copy stays as it was. --data merges into the pending copy when there is one, so two updates in a row stack. --publish makes the change live. entries list prints published* in the STATUS column for an entry with pending changes, and entries get includes the draft property.

Terminal window
npx plenary entries create blog_post --data '{"title":"Hello"}' --slug hello --publish
npx plenary entries update blog_post hello --data '{"title":"Hello again","subtitle":null}' --note "Fix typo"
npx plenary entries update blog_post hello --data '{"title":"Live now"}' --publish
npx plenary entries publish 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11
npx plenary entries unpublish 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11 --draft merge
npx plenary entries discard 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11 --note "Not this week"
npx plenary entries archive 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11 --note "Retired" -y
npx plenary entries archived blog_post
npx plenary entries restore 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11 --note "Back on"
npx plenary entries delete 2f1c9a0e-7c1b-4f7e-9a51-0d6a3f2b8c11 -y

entries unpublish on an entry with pending changes needs --draft merge (the pending changes become the draft’s content) or --draft discard (the live content is kept); without it the server answers entry_draft_pending.

entries archive takes --note <text> and -y, --yes. It archives the entry: it keeps its history and can be restored from the console’s Archived view while its model tracks revisions.

entries archived <model> lists the model’s archived entries, newest first: id, slug, title, when it was archived, and by whom, with the total under the table. It takes --limit <n> (up to 200) and --offset <n>, and needs content:revisions:read. entries restore <id> brings an archived entry back as a draft under its original id, with its history intact; it takes --note <text>. An entry that is not archived is refused.

entries delete permanently deletes the entry and its whole revision history, whether it is live or already archived, and nothing can restore it. It takes -y, --yes and no --note, since a permanent delete records no revision.

Terminal window
npx plenary entries export blog_post --where status=published > posts.ndjson
npx plenary entries import blog_post posts.ndjson --publish
ok 2f1c9a0e-… hello
fail line 2: entry_slug_taken
1 created, 1 failed

import accepts lines produced by export or bare {"fields": {…}, "slug": "…"} objects. Every line is tried; failed lines are reported with their number, and the run exits 1 at the end if any failed. --publish publishes each entry after creating it.

--upsert lets you run the same file again, for example a seed script. Each line is matched by its slug, which is unique per site, model, and locale. A matching entry gets the line’s fields in place of its own and keeps any slug, folder, or schedule the line leaves out; it prints (updated). A matching entry that is published takes the line as pending changes, like any update, and --publish then makes it live. A line with no matching entry is created. With --upsert, a line without a slug fails. Exported lines carry draft; import reads a line’s data, the live copy.

ok 2f1c9a0e-… hello (updated)
ok 8b07d3c1-… second-post
1 created, 1 updated, 0 failed
Command Flags Does
media upload <files...> --folder <id>: media folder id. --folder-path <path>: media folder path, such as /brand/logos, instead of --folder. --private: store as a private asset. --skip-existing: skip a file whose name is already in the folder. Uploads each file and prints <id> <file name>. With several files, a failure is reported and the rest still upload. With --skip-existing, a file already in the target folder (--folder, or the root) prints <id> <file name> (exists) and is not uploaded again.
media list --search <text>: match file names and captions. --path <prefix>: only assets under this folder path. --limit <n>, --page <n>. Table of media: id, type, file, size, path, visibility.
media get <id> none One media item as JSON.
Terminal window
npx plenary media upload hero.jpg logo.svg
npx plenary media upload contract.pdf --private
npx plenary media list --search hero --path /brand --limit 20

Manage a model’s content folders with plenary folders, and the media library’s folders with plenary media folders. Both have the same subcommands. Content folder commands take the model key first and need a site key. Wherever a command takes a folder, give its id or its path.

Command Flags Does
folders list <model> none Table of folders: id, path, name, and the number of entries in each folder and its sub-folders.
folders get <model> <id-or-path> none One folder as JSON.
folders create <model> <path> --name <name>: display name. Defaults to the slug. Creates the folder. The last segment of the path is its slug; the rest must be an existing folder, or /.
folders delete <model> <id-or-path> -y, --yes: do not ask. Deletes the folder. Its sub-folders and entries move up to its parent.
media folders list, get, create, delete as above The same, for media folders, without the model key. list counts media instead of entries.
Terminal window
npx plenary folders create page /company --name Company
npx plenary folders create page /company/team --name Team
npx plenary entries create page --data '{"title":"About"}' --slug about --folder-path /company
npx plenary media folders create /brand
npx plenary media upload logo.svg --folder-path /brand --skip-existing

A folder slug uses lowercase letters, digits, and hyphens. If no site is configured, media folders covers every site your credential can read; if a path exists on more than one, pass --site.

plenary sites list prints every site: key, name, default locale, locales, timezone, and inactive when applicable. It works with an API key or a session, because every principal may list sites.

KEY NAME DEFAULT LOCALES TIMEZONE
marketing Marketing en-us en-us,es-mx America/Denver

Roles belong to a site, so these commands work on the configured site (--site, PLENARY_SITE_KEY, or siteKey). They need a super user’s session.

Command Does
roles list Table of the site’s roles: key, name, grant count, user count on the site, and system for the site’s Admin role.
roles get <key> One of the site’s roles, its site, and its grants.
KEY NAME GRANTS USERS
admin Admin 30 3 system
editor Editor 15 1

Needs a user session. Listing shows the keys of the sites where your roles hold admin:api_keys:read; a super user sees every key.

Command Does
api-keys list Table of keys: id, name, type, state (active, inactive, revoked), last used, expiry.
api-keys get <id> One key as JSON. Never includes a private key’s secret.
api-keys create Create a key. Prints the secret alone on stdout, once; details go to stderr.
api-keys delete <id> Delete a key. Asks first; -y, --yes skips the question.

api-keys create flags:

Flag Meaning
-n, --name <name> Required.
-t, --type <private|public> Key type. Default private.
--description <text> Description.
-g, --grant <spec> Private keys: a grant as key[,site=<site key>][,model=<model key>]. Repeatable. On a site-bound key, site= can be left out.
--site <key> The site the key belongs to (the global option). A public key reads that site, and defaults to the configured site. A private key’s grants are held to it; a private key gets a site only from an explicit --site, and without one it is instance-wide, which needs a super user.
--expires <iso> Expiry timestamp (RFC 3339).
--origin <origin> An allowed browser origin. Repeatable.
--rate-limit <n> Requests per minute. 0 (default) is unlimited.
--include-drafts Public keys: read draft content too.

The key is created active. Because the secret is the only thing on stdout, you can capture it:

Terminal window
KEY=$(npx plenary api-keys create --name "Deploy job" --site marketing \
--grant content:models:read --grant content:models:update \
--grant content:entries:read)
npx plenary api-keys create --name "Marketing browser" --type public \
--site marketing --origin https://www.example.com

Runs a GraphQL query against the configured site, or prints the site’s schema.

plenary graphql [options] <query>
plenary graphql schema
Argument or flag Meaning
<query> The document: inline text, @file, or - for stdin.
-V, --var <name=value> A variable. The value is parsed as JSON when it is JSON (limit=3, where={"status":{"eq":"published"}}), otherwise kept as a string (tag=news). Repeatable.
--variables <json> All variables as one JSON object: inline, @file, or - for stdin. --var wins over it.
--operation <name> The operation to run when the document holds several.

The query needs a site key and a credential, like the entries commands. The site goes on the URL; when the document declares a $locale variable the flags leave unset, it is filled from --locale, PLENARY_LOCALE, or the site’s default locale. The response is printed as JSON: data, with errors beside it when a field failed. A response with errors exits 1 with the first error’s code on stderr.

schema prints the SDL in the credential’s variant, so a public key sees the public projection. Save it for a code generator:

Terminal window
npx plenary graphql '{ post(limit: 3, sort: [PUBLISHED_AT_DESC]) { items { slug title } total } }'
npx plenary graphql @posts.graphql --var limit=3 --operation Posts
npx plenary graphql schema > schema.graphql

Calls any endpoint and prints the response body, for anything without a dedicated command.

plenary api [options] <method> <path>
Argument or flag Meaning
<method> GET, POST, PUT, PATCH, DELETE, or HEAD.
<path> A path such as models (resolved under /api/v1/) or a full path such as /api/v1/models.
-d, --data <json> Request body: inline JSON, @file, or - for stdin.
-q, --query <key=value> Query parameter. Repeatable.
-H, --header <key:value> Request header. Repeatable.
-i, --include Print the status line and response headers to stderr.

The body is printed whatever the status. A non-2xx response exits 1 with the error code on stderr. The request carries the API key if one is configured, otherwise the session, otherwise nothing.

Terminal window
npx plenary api GET models
npx plenary api GET content/blog_post -q site_key=marketing -q limit=5
npx plenary api POST content/blog_post -q site_key=marketing -d '{"fields":{"title":"Hello"}}'
npx plenary api PUT models/6f1c2d3e-0000-4000-8000-000000000000 -d @model.json
npx plenary api DELETE media/ce221afb-0ef2-4fc6-94d6-8c3da0cc391e -i
  • Models as Code: the metadata workflow end to end.
  • API Keys: creating the key the CLI uses in CI.
  • Errors: every error code the CLI can print.