Your tenant.
Terminal-ready.

Overview

Manage your Crystallize tenants from the terminal: install boilerplates, create tenants, upload images and run mass operations. Use it locally, or in your CI/CD pipelines to automate the work.

The CLI is written in Bun and compiled into a single binary with everything included, so you need neither Node nor Bun. The install script is open source: it detects your OS and architecture, and downloads the latest release from GitHub.

What it does

• Boilerplates. Clones the repository, creates the tenant, imports its data, writes the .env file and installs the dependencies.
• Tenants. Creates empty tenants and generates invitations for existing ones.
• Tokens. Fetches and generates access tokens.
• Images and files. Uploads and registers a single file or a whole folder.
• Mass operations. Dumps your content model as JSON, validates and runs mass operations, and executes sets of mutations.
• Plugins. Scaffolds a plugin from a skeleton, generates its keypair and wires up its configuration in one command.
• Superfast Shop. Builds your own shop from a Superfast Shop demo, with your coding agent.
• Coding agents. Adds the Crystallize MCP server and AI skills to your environment.

Credentials

Most commands are interactive: when credentials are missing or input is needed, the CLI asks. In CI, pass --no-interactive where a command supports it.

When you save credentials interactively, the CLI stores them in ~/.crystallize/credentials.json. It looks for credentials in this order:

1. Environment variables: CRYSTALLIZE_ACCESS_TOKEN_ID and CRYSTALLIZE_ACCESS_TOKEN_SECRET
2. Options: --token_id and --token_secret
3. Stored file: ~/.crystallize/credentials.json

Run login to set up your credentials, and whoami to check they are valid.

Commands

Run ~/crystallize on its own to see the help and install shell completion. Add --help to any command to see its arguments and options.

Superfast Shop

Builds your own shop from a Superfast Shop demo, with your coding agent. The CLI asks which demo to start from, finds the coding agents installed on your machine, and hands your terminal over to the one you pick, with the demo's prompt.

• Run it in an interactive terminal: your coding agent takes it over.
• If no supported agent is installed, the CLI gives you the demo's prompt to paste into the agent of your choice.
• Its alias is sfs.

Boilerplates

An interactive command that does the tedious setup of a boilerplate for you.

Plugins

Scaffolds a new Crystallize plugin from a git skeleton you pick.

The command downloads the skeleton (a git repository, or a subfolder of a monorepo), generates an RSA JWK keypair (public.jwk.json and private.jwk.json, with the private key added to .gitignore), replaces the mustache tokens and installs the dependencies.

Tokens are replaced in file contents and in file and folder names: {{plugin_name}}, {{plugin_identifier}}, {{author_name}}, {{vendor_url}}, {{public_jwk}}, {{private_jwk}} and {{kid}}. Any *.dist template is first copied to its final name (.env.dist becomes .env), without overwriting an existing file.

In CI and scripts

Pass every input as an option and run without prompts:

The other plugin commands, keygen, encrypt-secret and decrypt-payload, generate keys and let you test the plugin payload protocol locally.

Tenants

Create a tenant

Creates a new tenant and removes the default shapes, so you start clean.

• Runs without prompts with --no-interactive when credentials are available.
• If the identifier is taken, the CLI tells you and suggests another one.

Invite users

Generates invitation links for new users.

Images

Uploads images and registers them in the Asset Organizer.

1{
2  "clean-name-png": "crystallize-key",
3  "images-crystallize-png": "my-tenant/25/1/12/3435d2d0/images/crystallize.png"
4}

Mass operations Experimental

Create, update and publish data in bulk. These commands dump, validate and run mass operation files, and execute sets of mutations from your machine.

Dump the content model

Creates a mass operation file that holds your content model: shapes and pieces.

Use --force to overwrite an existing file.

Validate a mass operation file

Checks a mass operation file against the schema, locally. It needs no credentials and no network, so it fits CI and pre-commit checks.

• Exits with a non-zero status code when the file is invalid.
• Groups issues by operation index, with the field path, the message and the Zod error code.

Run a mass operation

Uploads the file, registers the operation and waits for it to finish.

Use --legacy-spec to convert an old spec file into a mass operation file.

Execute mutations

A client-side tool to automate mutations.

Mutation format

1{
2  "create-products": {
3    "target": "pim",
4    "mutation": "mutation CreateProduct($input: CreateProductInput!) { product { create(language: \"en\", input: $input) { id } } }",
5    "sets": []
6  },
7  "publish-items": {
8    "mutation": "mutation PublishItems($ids: [ID!]!) { publishItems(language: \"en\", ids: $ids) { success { itemId } } }",
9    "target": "core",
10    "sets": [
11      {
12        "ids": [
13          "$create-products[0].product.create.id"
14        ]
15      }
16    ]
17  }
18}

Dependencies

Reference the result of an earlier operation to pass its IDs along, such as $create-products[0].product.create.id.

Injected variables

• $root.TENANT_ID
• $root.TENANT_DEFAULT_VATTYPE_ID
• $root.TENANT_ROOT_ID

Image mapping

1{
2  "images": [
3    {
4      "key": "$images.crystallize-key"
5    },
6    {
7      "key": "$images.my-tenant/25/1/12/3435d2d0/images/crystallize.png"
8    }
9  ]
10}

Contributing

The CLI lives in the CrystallizeAPI/tools monorepo. This repository is a read-only split of it, so open issues and pull requests on CrystallizeAPI/tools.