Quillet
Menu
Menu

Install and sign in

6 min read

Install @quilletcms/cli from npm, then give it a personal token or a CLI key so it can work on your project from a terminal or a CI job.

Why engineers get a way in besides the dashboard

The dashboard is where content managers write and publish. Engineers also need to change content from a repository, a build or a pipeline, and none of those can click a button. The command line, @quilletcms/cli, is that second way in. It speaks the same management API the dashboard uses, so what it writes is a version like any other, with the same history and the same publish step.

The CLI works inside a project that already exists. Creating a project, inviting people and minting keys are decisions a person makes in the dashboard. The CLI is handed a credential. With it, the CLI works on the project's content, files and environments. It has no password sign-in and no registration, so a content manager who never opens a terminal never meets it.

How the CLI signs in and which credential it uses

Before the CLI can do anything, it has to be installed in your repository and handed a credential. This part covers the package first, then the two kinds of credential it accepts and the order in which it looks for one.

The package

The CLI is the npm package @quilletcms/cli, version 1.0. It needs Node 22.13 or later and installs one command, quillet. Install it into the repository it works on, as a development dependency, so that everyone on the team and the CI job run the same version.

Two credentials

The CLI signs in with a token and nothing else. Both kinds are written <keyId>:<secret>:

Credential Made where Id starts with Acts as
Personal access token your Account page qt_ you, with your role in every project you belong to
CLI key the project's Settings → Keys qk_ the key, with the scopes it was given, in one project

Use a CLI key for a repository and for CI. It holds only the scopes you tick, out of content:read, content:write, content:publish and assets:private, and the versions it writes are recorded as the key's, as key:qk_…. Use a personal token for work that only a person may do. envs create and envs delete are owner routes, and an API key never has the owner role, whatever its scopes. Run one of them with a key and the CLI answers:

This needs the owner role, which an API key never has.
Sign in with a personal token to do this.

Access explains why ownership belongs to a person.

Where the credential comes from

For every command, the CLI takes the first of these that it finds:

  1. --key <keyId>:<secret>, for one run.
  2. The QUILLET_MANAGEMENT_KEY variable.
  3. The entry quillet login stored for the API URL in force.

If it finds none of them, it exits with code 4 and tells you which one to set. The store is ~/.quillet/credentials, with one entry per API URL. It is written with mode 0600, and the CLI refuses to read it once anyone but you can. QUILLET_HOME moves the .quillet directory somewhere else.

login checks the pair against the API before it stores anything, so a mistyped secret is refused straight away rather than on the next command. The secret never appears in output, in an error message or in a URL.

An http:// address works, for a CMS on your own network. Anywhere but localhost, though, the CLI warns on every run, because every request carries the key and plain http sends it unencrypted.

How to

Install the CLI into your repository and check that it runs:

npm install --save-dev @quilletcms/cli
npx quillet --version

It prints 1.0.0. Next, mint a credential. For a CLI key, an owner opens the project's Settings → Keys, presses New key, chooses Kind CLI, leaves Environment on Every environment, ticks the scopes and presses Create key. For a personal token, open the account menu, choose Account and press New token. Either way, the secret is shown only once. Copy it now.

Sign in. The CLI asks for the Key id and then for the Secret, which it does not echo:

npx quillet login --api-url <api-url>
Signed in to http://localhost:3000 as cli key qk_7f3… "deploy" on project handbook, env all, scopes content:read, content:write, content:publish.

You can ask at any time which credential is in force:

npx quillet whoami --api-url <api-url>

A key prints its project, its environment (all for a project-wide key) and its scopes. A token prints your name, your email and (via token). Once your repository has a .quilletrc that names the CMS, you can leave out the --api-url. Configure covers that file.

In CI, do not log in. Put the key in the job's secret store and expose it to the job as a variable:

export QUILLET_MANAGEMENT_KEY=<keyId>:<secret>
npx quillet whoami --api-url <api-url>

Off a terminal, login does not ask; it reads the id from --key-id <keyId> and the secret from standard input. Outside a throwaway shell, prefer the variable to --key: a command-line argument shows in ps and stays in your shell history.

When you are done with a CMS, forget the credential stored for it:

npx quillet logout --api-url <api-url>

Every command also takes --json, which prints one JSON document on stdout and nothing else. Scripting covers that flag, and the exit codes.

Limits

  • There is no password sign-in, no OAuth and no registration. A person who signs in to the dashboard with GitHub or Google mints a personal token to use the CLI.
  • The CLI cannot create a project, a key, a token or a member. You make those in the dashboard.
  • The store keeps one credential per API URL. To switch between a key and a token on the same CMS, log in again, or set QUILLET_MANAGEMENT_KEY for the run.
  • The store is a JSON file protected by its file permissions, not by the operating system's keychain.
  • A personal token cannot be narrowed to one project or to some of the scopes. Use a CLI key for that.
  • projects list reads a route that answers only a dashboard session in CMS 1.1, so it refuses every CLI credential with exit code 4. Use projects show for the project you are configured for.
  • Configure: .quilletrc, and how it names the project and the environment.
  • Command reference: every command, flag and exit code.
  • Access: the four credentials, and what each one may touch.
  • Your account: how to create and revoke personal tokens.
  • Authentication: which route accepts which credential.

Last updated