Crystallize CLI
The ultimate CLI for managing your Crystallize project.
Context
This new version is fully written in Bun and can be installed in a much more standard way. The CLI is built for the future of Crystallize, whether you're using it locally to enhance your Developer Experience or within your CI/CD pipelines to automate tasks.
Fun fact: You don't even need Node or Bun to run it—it's pre-compiled with everything included.
Replacing Legacy CLIs
Two older CLIs—@crystallize/cli
and @crystallize/cli-next
—are now deprecated. These were available on NPM and installable via npx
(or similar), and while they still function, they are now primarily used for installing legacy templates.
Installation
curl -LSs https://crystallizeapi.github.io/cli/install.bash | bash
Concerned about what this script does? It's fully open-source, so you can review it yourself. It primarily detects your OS and platform to download the latest version of the CLI from GitHub.
Features
The CLI enhances Developer Experience while also being CI/CD-friendly for automation.
Boilerplate Installation: Automates tedious setup steps:
- Cloning the repository
- Creating the tenant
- Populating data in the tenant
- Setting up the
.env
file - Installing dependencies
Tenant Management: Currently supports
create
for empty tenants and generatinginvitations
for existing ones. Future contributions are welcome!Token Management: Fetch and generate access tokens easily.
Image Uploads: Quickly upload and register images, whether a single file or an entire folder.
Mass Operations: Experimental but functional. You can
dump
your content model as JSON,run
mass operations, andexecute
sets of mutations.
Interactivity
Most commands are interactive. If credentials are missing, or input is required, the CLI will prompt you. To disable interactivity (e.g., in a CI environment), use --no-interactive
where applicable.
Credentials
The CLI stores credentials in ~/.crystallize/credentials.json
when saved interactively. It checks for credentials in the following order:
- Environment variables:
CRYSTALLIZE_ACCESS_TOKEN_ID
andCRYSTALLIZE_ACCESS_TOKEN_SECRET
- Command options:
--token_id
and--token_secret
- Stored file:
~/.crystallize/credentials.json
Boilerplate Installation
An interactive command designed to simplify setting up boilerplates.
~/crystallize boilerplate install <folder> [tenant-identifier] [boilerplate-identifier]
folder
(required): The installation directory.tenant-identifier
andboilerplate-identifier
(optional): If omitted, a wizard will guide you.
Tenant Management
Creating a Tenant
Creates a new tenant and removes default shapes for a clean setup.
~/crystallize tenant create <tenant-identifier>
- Runs non-interactively with
--no-interactive
if credentials are available. - If the identifier is taken, the CLI will inform you and suggest an alternative.
Inviting Users to a Tenant
Generates invitation links for new users.
~/crystallize tenant invite <tenant-identifier>
Options:
--role
: Default istenantAdmin
, but other roles are available.--expiry
: Default is 6 hours; you can customize it.--number
: Default is 1; you can generate multiple invites.
Image Upload
Uploads and registers images in the Asset Organizer.
~/crystallize image upload <tenant-identifier> <file> [output-file]
file
can be a single file or a folder (uploading all contained images).output-file
(optional) stores mappings for automation.
Example output:
{
"clean-name-png": "crystallize-key",
"images-crystallize-png": "my-tenant/25/1/12/3435d2d0/images/crystallize.png"
}
Use --force
to overwrite an existing output-file
.
Mass Operations
Dumping the Content Model
Creates a Mass Operation file containing the content model (Shapes and Pieces).
~/crystallize mass-operation dump-content-model <tenant-identifier> <file>
Use --force
to overwrite an existing file.
Running a Mass Operation
Executes a Mass Operation file by uploading it, registering the operation, and waiting for completion.
~/crystallize mass-operation run <tenant-identifier> <file>
- Use
--legacy-spec
to convert an old Spec File to a Mass Operation file.
Executing Mutations
A client-side utility to automate mutations.
~/crystallize mass-operation execute-mutations <tenant-identifier> <file> [image-mapping-file]
file
: Contains the mutations (format below).image-mapping-file
(optional): Injects image paths into variables.
Mutation Format
{
"create-products": {
"target": "pim",
"mutation": "mutation CreateProduct($input: CreateProductInput!) { product { create(language: \"en\", input: $input) { id } } }",
"sets": []
},
"publish-items": {
"mutation": "mutation PublishItems($ids: [ID!]!) { publishItems(language: \"en\", ids: $ids) { success { itemId } } }",
"target": "core",
"sets": [{ "ids": ["$create-products[0].product.create.id"] }]
}
}
Dependency Management
Use references like $create-products[0].product.create.id
to pass IDs from one operation to another.
Injected Variables
$root.TENANT_ID
$root.TENANT_DEFAULT_VATTYPE_ID
$root.TENANT_ROOT_ID
Image Mapping File
{
"images": [
{ "key": "$images.crystallize-key" },
{ "key": "$images.my-tenant/25/1/12/3435d2d0/images/crystallize.png" }
]
}
Contributing
The CLI resides in CrystallizeAPI/tools, a read-only split from the main repo.
For issues or contributions, submit them to the main repository: CrystallizeAPI/tools.