Command Line

Keystone's command line interface (CLI) has been designed to help you develop, build, and deploy your Keystone project.

Using the keystone-next command you can start the dev process, build and run your app in production, and control how you migrate the structure of your database as your schema changes.

Usage

$ keystone-next [command]

Commands
  dev           start the project in development mode (default)
  postinstall   generate client APIs and types (optional)
  build         build the project (must be done before using start)
  start         start the project in production mode
  prisma        run Prisma CLI commands safely

All the commands expect to find a module called keystone.js (or .ts) with a default export that returns a Keystone System config() from @keystone-next/keystone/schema. See System Configuration for details.

Setting up package.json

We recommend adding the following scripts to your project's package.json file:

{
  "scripts": {
    "deploy": "keystone-next build && keystone-next prisma migrate deploy",
    "dev": "keystone-next dev",
    "postinstall": "keystone-next postinstall",
    "start": "keystone-next start"
  }
}

Note: the deploy script above assumes you are using migrations

Read on below for more details about each command, and see bringing it all together for more details (including some important caveats) about how that "deploy" command works.

dev

$ keystone-next dev

This is the command you use to start Keystone for local development. It will:

• Generate the files required by Keystone's APIs and Admin UI
• Generate and apply database migrations based on your Keystone Schema
• Start the local dev server, which hosts the GraphQL API and Admin UI

Keystone does not currently watch your local files for changes. If you update the config, schema or any other files in your keystone project you'll need to restart the server.

About database migrations

In development, Keystone will migrate the structure of your database for you in one of two ways depending on how you have configured db.useMigrations:

• If db.useMigrations is false (the default), Keystone will use Prisma Migrate to update your database so that it matches your schema. It may lose data while updating your database so you should only use this mode in initial development.
• If db.useMigrations is true, Keystone will use Prisma Migrate to apply any existing migrations and prompt you to create a migration if there was a change to your schema.

When you are using migrations, the recommended workflow is to have keystone-next dev generate the migrations for you and apply them automatically in development.

Commit the migration files to source control, then when you are hosting your app in production, use the keystone-next prisma migrate deploy command (see below) to deploy your migrations before starting Keystone.

We strongly recommend enabling migrations if you are going to run your app in production. Not doing so risks data loss.

Resetting the database

From time to time, in development you may want to reset the database and recreate it from scratch. You can do this by passing the --reset-db flag:

$ keystone-next dev --reset-db

Doing this will destroy your database, including all data

This is mainly useful early in a project's development lifecycle, when you want to test database initialisation scripts or create a fresh set of test data.

postinstall

$ keystone-next postinstall

Keystone generates several files that your app may depend on, including the Node.js API and TypeScript definitions.

While they are generated by Keystone's dev command, we strongly recommend you add the postinstall command to your project's package.json to ensure the files are always present and up to date; otherwise you may see intermittent errors in your code editor and CI workflows.

Fixing validation errors

The postinstall command will warn you if any of the generated files you should have committed to source control (such as the Prisma and GraphQL Schemas) are out of sync with your Keystone Schema.

While the recommended way to fix this problem is to start your app using keystone-next dev (which will update these files) and commit any changes into source control, if you need to you can use the --fix flag to have the postinstall command fix the files for you:

$ keystone-next postinstall --fix

build

$ keystone-next build

This command generates the files needed for Keystone to start in production mode. You should run it during the build phase of your production deployment.

It will also validate that the generated files you should have committed to source control are in sync with your Keystone Schema (see postinstall above).

start

$ keystone-next start

This command starts Keystone in production mode. It requires a build to have been generated (see build above).

It will not generate or apply any database migrations - these should be run during the build or release phase of your production deployment.

prisma

$ keystone-next prisma [command]

Keystone's CLI includes a prisma command which allows you to run any Prisma CLI commands safely within your keystone project.

It will ensure your generated files (importantly, the Prisma Schema) are in sync with your Keystone Schema, and pass the configured database connection string through to Prisma as well.

Working with Migrations

The primary reason you'll need to use the Prisma CLI in your Keystone project is to work with Prisma Migrate. For example, to deploy your migrations in production, you would run:

$ keystone-next prisma migrate deploy

This will run the Prisma migrate deploy command.

As you start working with more sophisticated migration scenarios, you'll probably also need to use the migrate resolve and migrate status commands.

While Keystone abstracts much of the Prisma workflow for you, we strongly recommend you familiarise yourself with the Prisma Migrate CLI commands when you are managing your application in production.

Bringing it all together

Although there are many subtle ways you might customise your workflow with Keystone based on your project's requirements, this is a fairly typical way of working:

Postinstall after git clone and pull

Setting up the postinstall script will make sure that Keystone's generated files are all present and correct when you get latest from source control and install dependencies.

This will also run in CI, which means your lint rules and tests will be using the latest version of your Keystone build.

Developing your project

Use keystone-next dev to start Keystone for development. Make sure you commit any changes to generated files, including both the Prisma and GraphQL Schema files, and migrations.

Deploying to production

Most application hosting platforms allow you to specify a build script (for new deployments) and a start script (for when the app is started, including new instances when scaling up).

Build Script

Install the project dependencies, generate the build and deploy migrations:

yarn && yarn keystone-next build && yarn keystone-next prisma migrate deploy

Note: it is only safe to run migrations in the build step if deploys are built synchronously by your hosting provider. Make sure you don't run migrations against your production database from staging / preview builds.

Start Script

Start Keystone in production mode:

yarn keystone-next start

Notes

• These examples use yarn as the package manager, you can use others like npm or pnpm if you prefer.
• The commands above are included in the package.json reference at the top of this page. We recommend using package scripts so your build and start commands are centralised in source control.
• If you promote your build through separate environments in a pipeline (e.g testing → staging → production) you should run migrations during the promote step and not as part of the build script.
• It is important you do not run migrations against your production database from staging builds. If you have staging or preview environments set up in production, make sure they are not pointed to your production database.