Convosite

Appearance

CLI ​

@convosite/cli keeps the developer-owned structure of a Convosite experience in your project.

Use it to create, validate, pull, and push Blocks and Endpoints. Knowledge, Media, Variables, and other site-managed data stay in Convosite and are not synced by the CLI.

Requirements ​

  • Node.js 20 or newer
  • A Convosite site
  • A Convosite access token

Installation ​

Install the CLI in your project:

bash
npm install --save-dev @convosite/cli

Run commands with npx:

bash
npx convosite --help

Commands ​

text
convosite init
convosite make:block <name>
convosite make:endpoint <name>
convosite validate
convosite pull [--force]
convosite push

Project structure ​

A typical project looks like this:

text
my-project/
├── blocks/
│   ├── text/
│   │   └── block.json
│   └── product/
│       └── block.json
├── endpoints/
│   └── contact/
│       └── endpoint.json
├── .env
└── convosite.config.json

The CLI recursively discovers files named block.json and endpoint.json inside the configured directories. This means you can keep component source files beside their definitions if that suits your project.

Configuration ​

convosite.config.json tells the CLI where your definitions live:

json
{
  "blocks": "./blocks",
  "endpoints": "./endpoints"
}

The blocks property is required. If endpoints is omitted, the CLI defaults to ./endpoints.

Authentication ​

Add your access token to the .env file in the directory where you run the CLI:

dotenv
CONVOSITE_ACCESS_TOKEN=cvt_...

Keep tokens private

Do not commit your Convosite access token to source control. Add .env to .gitignore and provide credentials through your normal secret-management process in CI.

The CLI loads .env from the current working directory before running commands.

Development workflow ​

A normal workflow is:

bash
npx convosite make:block product
npx convosite make:endpoint contact
npx convosite validate
npx convosite push

Commit your Block and Endpoint definitions with the rest of your application code.

If you need to bring the current remote definitions into another checkout or project, use:

bash
npx convosite pull

See Pull before using --force.

Source of truth ​

When you run push, your local Block and Endpoint definitions are the developer-managed source of truth. Convosite reports how many definitions were created, updated, and deleted.

This does not make the CLI the source of truth for Knowledge, Media, Variables, conversations, or other data managed through the Convosite platform.

Custom API URL ​

The CLI connects to https://app.convosite.io by default. The package also supports overriding this with CONVOSITE_API_URL in the environment. This is primarily useful when working against another Convosite environment.

Next steps ​

Convosite developer documentation