Command reference

This page lists every command of @quilletcms/cli 1.0, each flag with what it means and what happens when you leave it out, and the exit codes all of them share.

Arguments in <angle brackets> are required and those in [square brackets] are optional. A <key> is a document key such as docs/intro; folder settings (docs/_index), components (_schemas/hero) and singletons (_singletons/nav) are keys too. npx quillet <command> --help prints the same flags, and npx quillet help --json prints the whole tree as one document.

Global flags

Every command takes these, before or after its own name. The one typed nearest the command wins. The commands that ask before they act are publish (on a terminal only), unpublish, content delete, schemas delete, envs delete, assets delete, folders delete, restore, and backup over an existing archive. At a terminal each one waits for y, so a line pasted after it is read as the answer; --yes answers for you. Configure explains where the values come from when a flag is absent.

Flag	Meaning	Default
--api-url <url>	the CMS to talk to, an origin with no path	QUILLET_API_URL, then apiUrl in .quilletrc
--project <slug>	the project to work in	QUILLET_PROJECT, then project
--env <key>	the environment to work in	QUILLET_ENV, then env
--locale <locale>	the locale to read and write	QUILLET_LOCALE, then locale, then the project's default
--key <keyId:secret>	a credential for this run only	QUILLET_MANAGEMENT_KEY, then the stored login
--json	print one JSON document on stdout; errors as JSON on stderr	off
--yes	answer yes to every confirmation, so nothing waits for a reply	off: ask on a terminal, refuse with exit 2 off one
--quiet	leave out the summary line	off
--verbose	log each request's method, path and status to stderr	off
-V, --version	print the CLI's version	—
-h, --help	print the help for the command	—

Sign in

Install and sign in walks through these.

login

Stores a personal token or a CLI key for the API URL in force, after checking it against the API.

Flag	Meaning	Default
--key-id <id>	the id; off a terminal, the secret is read from stdin	asked for on a terminal

logout

Removes the stored credential for the API URL in force. It revokes nothing.

Flag	Meaning	Default
(none)	only the global flags	—

whoami

Prints who the credential in force is: a person with (via token), or a key with its project, environment and scopes.

Flag	Meaning	Default
(none)	only the global flags	—

projects

projects list

Every project the credential belongs to. CMS 1.1 answers this route only to a dashboard session, so a key and a token are both refused it, with exit 4.

Flag	Meaning	Default
(none)	only the global flags	—

projects show [slug]

One project: its locales, settings, your role and its limits.

Flag	Meaning	Default
[slug]	the project	the configured project

envs

envs list

Every environment of the project, with which one is the default.

Flag	Meaning	Default
(none)	only the global flags	—

envs show <env>

One environment, with how many documents and keys it holds.

Flag	Meaning	Default
<env>	the environment key	required

envs create <key>

Creates an empty environment. An owner route: a personal token only.

Flag	Meaning	Default
<key>	the new environment's key	required
--name <name>	what it is called	the key

envs delete <env>

Deletes an environment and everything in it, after asking. A personal token only.

Flag	Meaning	Default
<env>	the environment key	required

content

content list [prefix]

Lists documents, paging to the end. Folder settings are left out, as in the dashboard's tree.

Flag	Meaning	Default
[prefix]	only keys under this folder	the whole environment
--type <type>	only json, md or text documents	every type
--all-locales	repeat the listing for every project locale	the locale in force
--include-index	list each folder's _index too	off

content get <key>

Prints a document's body: JSON pretty-printed, Markdown and text as written.

Flag	Meaning	Default
<key>	the document key	required
--meta	print the view (title, versions, schema…) without the body	the body

content put <key>

Saves a file as the document's next version, a draft.

Flag	Meaning	Default
<key>	the document key	required
--file <path>	the file to send as the body	required
--type <type>	json, md or text	from the extension: .json, .md, anything else text
--title <title>	the title to store	not sent
--tags <tags>	comma-separated tags	not sent
--schema <name>	the component to bind the document to	not sent
--message <message>	what this save changed, kept on the version	none
--if-match <hash>	save only while the document still has this content hash	no guard

content delete <key>

Deletes the document in the locale in force, after asking; --yes answers for you. A document still in use is refused with exit 3, and the CLI lists what uses it.

Flag	Meaning	Default
<key>	the document key	required

content versions <key>

The document's history, newest first: number, time, author, published, message.

Flag	Meaning	Default
<key>	the document key	required
--limit <n>	stop after this many versions	every version

content restore <key> <version>

Writes an earlier version's body back as a new draft, with the message Restored v<n>.

Flag	Meaning	Default
<key>	the document key	required
<version>	the version number, as an argument	required
--publish	publish the restored draft in the same run	leave a draft

content refs <key>

What points at the document: key, locale and the path of the field.

Flag	Meaning	Default
<key>	the document key	required

content translations <key>

Every project locale of a key: source, missing, partial or translated, what it still inherits, and whether it needs review.

Flag	Meaning	Default
<key>	the document key	required

content review <key>

Records that the translation in --locale was read against the source's current version.

Flag	Meaning	Default
<key>	the document key	required
--locale <locale>	the translation to mark	required here

content work-queue

The documents with something outstanding, in the locale in force.

Flag	Meaning	Default
--view <view>	unpublished, missing, partial or needs-review	unpublished
--prefix <prefix>	only keys under this folder	the whole environment
--schema <name>	only documents bound to this component	any
--limit <n>	stop after this many rows	every row

publish

publish <keys...>

Makes the current draft of each document live, as one release. It prints what else changes first; on a terminal it then asks, unless you pass --yes, and off one it goes ahead. Publishing one document, a refusal the preflight finds stops it before anything is sent; in a batch it is a warning and the CMS decides.

Flag	Meaning	Default
<keys...>	one or more document keys	required
--impact	print what publishing would change, and stop	publish

unpublish <keys...>

Takes each document out of the live environment, after asking. Off a terminal it needs --yes.

Flag	Meaning	Default
<keys...>	one or more document keys	required

schemas

A component is the document _schemas/<name>, in the project's default locale. These commands are a shorter way to its content commands.

schemas list

The environment's components: draft and published versions, how many documents use each, and whether it is a page or a singleton.

Flag	Meaning	Default
(none)	only the global flags	—

schemas get <name>

Prints a component's JSON Schema.

Flag	Meaning	Default
<name>	the component	required

schemas put <name>

Saves a JSON file as the component's next version, a draft.

Flag	Meaning	Default
<name>	the component	required
--file <path>	the JSON file with the schema	required
--message <message>	what this save changed	none

schemas validate <name>

Checks every document the component is in force for. One line per failing document; exit 1 if any fail.

Flag	Meaning	Default
<name>	the component	required
--published	measure the published versions	the drafts

schemas delete <name>

Deletes a component, after asking. Refused with exit 3 while anything is bound to it.

Flag	Meaning	Default
<name>	the component	required

types

types

Writes a TypeScript declaration file for the environment's components. The file's first line keeps the ETag, so an unchanged run writes nothing and says is up to date. Generated types covers using it.

Flag	Meaning	Default
--out <file>	where to write the declarations	quillet.d.ts
--draft	type the drafts	the published versions

assets

Files belong to the project, not to an environment, so these commands ignore --env.

assets list

The project's files, then a line on stderr with the count and the space used against the quota.

Flag	Meaning	Default
--q <text>	search file names	every file
--mime <mime>	one type or family, such as image/*; may be repeated	every type
--folder <id>	only this folder, or root	every folder
--visibility <visibility>	public or private	both

assets show <id>

One file's metadata, its sha256 and the URL it is served from.

Flag	Meaning	Default
<id>	the file id	required

assets upload <files...>

Uploads one or more files, one after another. A file over 100 MB is refused before anything is sent. The CMS's own limit, ASSET_MAX_BYTES, is 25 MB unless your instance changed it.

Flag	Meaning	Default
<files...>	the files	required
--private	store them as private, served by signed URL only	public
--alt <text>	the description stored with every file	none
--folder <id|path>	the folder, by id or by a /-separated name path	the root

assets update <id>

Changes a file's name, description, visibility or folder. At least one flag is needed.

Flag	Meaning	Default
<id>	the file id	required
--name <name>	the name to show	unchanged
--alt <text>	the description	unchanged
--visibility <visibility>	public or private	unchanged
--folder <id>	the folder id, or root	unchanged

assets delete <id>

Deletes a file, after asking. A file still in use is refused with exit 3, and the CLI lists what uses it.

Flag	Meaning	Default
<id>	the file id	required

assets download <id>

Writes a file to disk, checked against its sha256. A file already at the target is kept unless you pass --yes.

Flag	Meaning	Default
<id>	the file id	required
--out <path>	where to write it	the file's own name, in the working directory

folders

The media library's folders, which hold files, not documents.

folders list

Every folder, as an indented tree with ids.

Flag	Meaning	Default
(none)	only the global flags	—

folders create <name>

Flag	Meaning	Default
<name>	the new folder's name	required
--parent <idOrPath>	a folder id, or a /-separated name path	the root

folders rename <id> <name>

Flag	Meaning	Default
<id>	the folder id, from the listing	required
<name>	its new name	required

folders delete <id>

Deletes an empty folder, after asking.

Flag	Meaning	Default
<id>	the folder id, from the listing	required

Sync

These read the sync section of .quilletrc and write quillet.lock beside it. Sync a repository explains the verdicts and the lock.

init

Writes the sync section, creates the content directory and pulls. Run again, it keeps the section and pulls.

Flag	Meaning	Default
--content-dir <dir>	where the files live	content
--scope <prefix...>	the folders this repository manages, like docs/	asked on a terminal; required off one
--locales <a,b>	only these locales	every project locale

diff

Every document in the scope that is not unchanged, grouped by verdict. Exit 3 when any is a conflict.

Flag	Meaning	Default
(none)	only the global flags	—

status

The one-line form of diff, with the same exit code.

Flag	Meaning	Default
(none)	only the global flags	—

push

Sends local changes as drafts, in batches of up to 500, components first.

Flag	Meaning	Default
--dry-run	print the plan and stop	send
--force	take the local copy, naming no base	refuse the push on a conflict
--allow-delete	delete documents the working copy no longer holds	skip them
--publish	publish what the push created or updated	leave drafts

pull

Brings the working copy up to the server. Local edits are kept and reported.

Flag	Meaning	Default
--force	overwrite local changes and remove what the server dropped	keep local work

Backup and restore

Backup and restore covers what an archive holds and what a restore refuses.

backup

Writes every environment, document, version and file to one archive.

Flag	Meaning	Default
--out <path>	where to write it; an existing one is replaced after asking	quillet-<project>-<YYYYMMDD-HHmmss>.tgz, in UTC
--dir	write a directory instead of a .tgz	a .tgz
--envs <keys>	the environments to walk, comma separated	every environment
--no-assets	archive the file index but not the bytes	bytes included

restore <archive>

Puts an archive back, with its history, into empty environments, after asking. The global --env, and only the flag, narrows it to one target. With --as-drafts nothing is staged: the target is the environment in force (--env, QUILLET_ENV or the file's env, one of which is required), documents are created or updated so the target need not be empty, and --dry-run only prints the plan.

Flag	Meaning	Default
<archive>	the directory or .tgz a backup wrote	required
--env <key>	restore one environment into this one (full fidelity; with --as-drafts, the environment in force)	every archived environment into its own name
--dry-run	stage, print the plan, and throw the staged import away	restore
--as-drafts	recreate the newest version of each document, losing the history	full fidelity
--publish	publish what the archive had published; with --as-drafts only	off

help

help [names...]

The same help as --help, for the whole tree or one command. With --json it describes the commands, their arguments and options, and the global flags once, as data.

Flag	Meaning	Default
[names...]	a group or a command, such as content put	the whole tree
--json	print the description as JSON	prose

Exit codes

Every command ends with one of these. Under --json a non-zero exit also writes { "error", "message", "fields", "hint" } on stderr. Scripting shows how to act on them.

Code	Meaning	For example
0	done	a push that wrote, a diff with no conflict, --help
1	the API refused, or something failed	a 404 or a 422, an unreachable CMS, schemas validate with failures, a confirmation answered no
2	usage	an unknown command or flag, no project or environment, an unset ${NAME} in .quilletrc, a confirmation with no terminal and no --yes
3	a decision the data forces	a conflict in diff or push, any 409 such as a document in use or a non-empty restore target, a restore that committed only some environments
4	no credential, or it was refused	nothing to sign in with, a 401, any 403 such as an owner route with a key or a missing scope