CLI

Keep the content model and frontend in sync#

The Contoprix CLI works with the content model: content types, component types, fields, nested fields, options, relations, and behavior settings. It does not copy content entries, pages, drafts, published versions, media files, users, or webhook secrets.

Use it to pull a reviewed model into source control, generate TypeScript types, scaffold custom React renderers, and safely promote a schema between environments.

Requirements#

• Node.js 22 or newer
• A running Contoprix API
• A project where you can create contoprix.config.json
• An API client with schema:read; add schema:write only when the project must push a model

Install it globally or as a development dependency. A local install is usually easiest for a team because it can be versioned with the project.

npm install --save-dev @contoprix/cli
npx contoprix --help

Quick start#

Run these commands from the root of your frontend project:

npx contoprix init
npx contoprix login
npx contoprix pull
npx contoprix generate
npx contoprix components
npx contoprix validate

Here is what each step does:

After the first run, a project normally contains:

contoprix.config.json
.contoprix/
  schema/
    schema.json
src/
  contoprix/
    generated.ts
  components/
    contoprix/
      registry.ts
      Hero.tsx

Create project configuration#

npx contoprix init asks for the API origin, default language, optional website ID, component directory, and generated output directory. It creates contoprix.config.json and does not overwrite an existing file.

Example configuration:

{
  "baseUrl": "https://cms.example.com",
  "websiteId": "website-id",
  "environment": "development",
  "languageCode": "en",
  "outputDir": "src/contoprix",
  "componentsDir": "src/components/contoprix",
  "schemaDir": ".contoprix/schema",
  "generatedTypesFile": "src/contoprix/generated.ts",
  "graphqlGeneratedTypesFile": "src/contoprix/graphql-generated.ts"
}

All relative paths are resolved from the directory where you run the CLI.

Log in securely#

Run:

npx contoprix login

Enter the API origin, client ID, and client secret for a schema-scoped API client. Use only the origin, for example https://cms.example.com; do not append /api.

The CLI verifies the credentials against the schema endpoint before saving them in its local credential store. Do not commit that local credential file, copy it into a frontend bundle, or print it in CI logs.

Use npx contoprix logout to remove the local credentials. If a secret is compromised, also revoke or rotate the API client in Contoprix Admin.

Pull, generate, and render#

When an editor or developer changes the content model, run:

npx contoprix pull
npx contoprix generate
npx contoprix components
npx contoprix validate
npm run build

pull writes the remote model to .contoprix/schema/schema.json by default. generate writes model interfaces to src/contoprix/generated.ts by default. Generated files start with a notice; do not hand-edit them.

components creates custom React component stubs only when they do not already exist. It also refreshes the component index and registry. If you intentionally want to overwrite existing stubs, use the explicit destructive option:

npx contoprix components --force

Review the generated changes before committing. A missing custom component is not automatically an error: the React SDK can use its generic, schema-driven fallback renderer for unregistered renderable types. validate reports which types have custom renderers and which use the fallback.

npx contoprix sync is a shortcut for pull followed by generate. It does not scaffold component overrides.

Push a reviewed schema#

push applies your local schema to the connected Contoprix environment. It needs both schema:read and schema:write.

Always preview before a production change:

npx contoprix push --dry-run

After review, apply the change:

npx contoprix push

For an approved non-interactive automation job:

npx contoprix push --yes

Push is intentionally additive and update-oriented:

• definitions are matched by stable code;
• missing definitions are created;
• existing definitions are updated;
• nested fields and options are upserted;
• remote definitions absent from the local schema are not deleted; and
• validation runs before the operation is saved.

The deprecated deploy command delegates to push. Use push in new scripts.

Promote a model between environments#

One safe staging-to-production workflow is:

1. Log in to staging and run contoprix pull.
2. Review and commit the model JSON and generated types.
3. Log in to production with a restricted schema API client.
4. Run contoprix push --dry-run.
5. Review the reported create and update counts.
6. Run contoprix push after approval.
7. Run contoprix pull again and confirm the resulting model is expected.

Do not use CLI schema push as a substitute for content migration. Entries, media, relationships between existing records, and publication states need a separate migration plan.

Generate GraphQL types too#

The GraphQL schema is generated per tenant. Use the GraphQL subcommands after logging in with schema:read:

npx contoprix graphql pull
npx contoprix graphql generate

# Or run both:
npx contoprix graphql sync

The CLI saves the introspection export at .contoprix/schema/graphql-schema.json and writes generated types to src/contoprix/graphql-generated.ts by default. Regenerate after a content-model change before relying on a new GraphQL field.

Use the CLI in CI#

For a build that validates already committed generated files, keep the workflow small:

steps:
  - name: Install dependencies
    run: npm ci

  - name: Validate Contoprix project files
    run: npx contoprix validate

  - name: Build application
    run: npm run build

Only add remote pull or push in CI when the runner can receive the credentials from a secure secret store. Keep production push behind an approved deployment stage and run --dry-run first.

Troubleshooting#

Use the SDK once the model is in your project, and the GraphQL guide for generated tenant-specific query types.