The umbot CLI for creating voice skills and chatbots

This page is machine-translated from the Russian original. If something reads oddly, the Russian version is the source of truth — open an issue.

A CLI utility for quickly creating and configuring projects based on the multi-platform umbot framework. It lets you generate a ready-made structure for voice skills (Alice, Sber SmartApp, Marusia) or chatbots (Telegram, VK, Viber, MAX) with a single command.

It also lets you:

• Create new projects from ready-made templates
• Configure the project
• Generate the basic application structure

🚀 Quick start

Install the framework and create a new project:

npx umbot create my-bot
cd my-bot
npm install
npm run build
npm start
Copy

npm install creates package-lock.json. Keep it in the repository together with the source code: it pins the tested dependency versions for CI and Docker builds.

After that, the application is available locally. To run it, use npm run build && npm start — this applies both to the default/quiz templates and to projects generated with create from-flow. For interactive debugging in the console (without an HTTP server), create a project in the dev mode — then index.ts uses BotTest and the test() method.

📋 CLI commands

Command	Description	Parameters
create	Create a new project	<project-name> or <config-file.json>
create from-flow	Create a project from the visual editor	<flow.json> [--output ./path] [--usecloud] [--force]
validate	Check that flow.json is valid	<flow.json>
stats	Aggregate metrics from a log	--log <path>
generateenv	Generate a .env file in the current folder	[--force]
doctor	Check the project, tokens and webhooks	[--env <path>] [--offline]
webhook	Register a Telegram/MAX webhook with a secret	<telegram|max> <https-url>
add docker	Add a Dockerfile and .dockerignore to the current folder	-
add deploy	Add .github/workflows/deploy.yml	-
add env	Generate .env in the current folder	[--force]
add platform	A scaffold of your own platform adapter with a test	<Name> [--force]
add db	A scaffold of a database adapter with a test	<Name> [--force]
add middleware	A middleware scaffold with a test	<name> [--force]
-v, version	Show the CLI version	-

Adapter and middleware scaffolds: add platform, add db, add middleware

The commands are run in the project root (where the src/ folder is) and create a module together with a test:

Command	Files
npx umbot add platform <Name>	src/platforms/<Name>Adapter.ts, <Name>Adapter.test.ts
npx umbot add db <Name>	src/db/<Name>DbAdapter.ts, <Name>DbAdapter.test.ts
npx umbot add middleware <n>	src/middleware/<name>.ts, <name>.test.ts (a factory function)

The name is written in Latin letters: discord, my-chat, Postgres. You can omit the Adapter suffix. For a platform adapter, platformName is derived from the name (my-chat → my_chat).

The scaffold compiles and passes its tests right away. The places you need to fill in for your platform or database are marked with a TODO comment:

• platform — a chat platform with a webhook: it recognizes the request, passes the text to the commands and sends the reply via Request (the request has a time limit). Unknown events get a response without calling the commands: on an error the platform would redeliver the update. You need to fill in the request format, the API address, authorization and the button format;
• database — a working adapter that keeps data in process memory. Its methods are replaced with calls to your database driver. The tests check the responses the framework expects, including separate records for the same userId on different platforms (uniqueKeys);
• middleware — a factory with options, using user blocking as the example.

The tests are written with the built-in node:test and need no extra dependencies. Run them with the command the CLI prints after generation:

npx umbot add platform discord
npm run build && node --test dist/platforms/DiscordAdapter.test.js
Copy

The CLI does not change src/index.ts: it prints the connection lines (bot.use(...)) to the console. Existing files are not overwritten without --force. How each method works is described in the guides on the platform adapter, DB adapter and middleware.

The webhook command

npx umbot webhook <telegram|max> <https-url> enables webhook signature verification with a single command. Run it in the project folder: the token is taken from .env (TELEGRAM_TOKEN / MAX_TOKEN) or the environment. The command generates a secret, registers the webhook with it right away (setWebhook for Telegram, POST /subscriptions for MAX) and saves the secret to .env as TELEGRAM_WEBHOOK_SECRET / MAX_WEBHOOK_SECRET. The framework reads these variables itself and starts rejecting requests without the correct secret. The secret is written to .env only after a successful registration, and if it is already there, the existing one is used. For VK, the secret key is set in the community's Callback API settings (VK_SECRET_KEY in .env).

npx umbot webhook telegram https://bot.example.com/webhook
Copy

The doctor command

npx umbot doctor in the project folder checks whether the bot is ready to run and prints a report:

• the Node.js version suits umbot, the umbot package is installed;
• .env exists and is listed in .gitignore (otherwise tokens get into git — this is an error);
• the platform tokens from .env and the environment work: a request to the API (Telegram getMe, MAX GET /me, VK groups.getById, Viber get_account_info, Alice — the file upload quota). For SmartApp and Marusia only the presence of the token is checked;
• webhooks: the address, the number of pending updates and the last Telegram delivery error, MAX subscriptions, the Viber webhook; a warning if the webhook is registered without a secret. Without a webhook — a hint about bot.startPolling().

Tokens do not get into the report. --offline disables API requests, --env <path> sets another .env file. On errors the command exits with code 1 — you can run it in CI before deploying.

npx umbot doctor
Copy

create command flags

Flag	Description
--minimal	Creates a minimal working project without a controller class: all the logic is described directly in index.ts with addCommand (the project configs are generated as usual). Suitable for a quick prototype. Works only with the default type.
--prod	Creates a production-ready project: Dockerfile, .dockerignore and .github/workflows/deploy.yml. The .env file is created in every project, see below.
--usecloud	Generates a Yandex Cloud Functions application: adds serverless.yml, disables the local HTTP listener. Applies only to create from-flow.
--force	Allows overwriting a non-empty target directory. Otherwise the CLI stops with an error so as not to erase your files.

💡 Important: the --minimal flag does not apply to the quiz type, since a quiz requires complex logic and state storage.

The .env file. A project created by create always reads .env (env: './.env' in src/config/*Config.ts), and the CLI creates it with empty variables for tokens, webhook secrets and MongoDB — fill in the ones you need. Empty values are skipped by the framework. An existing .env is not overwritten. If there is no file (Docker, serverless), the variables are taken from the process environment. The generateenv and add env commands write the same template to the current folder.

🛠 Usage examples

A simple project (a basic application)

To quickly create an application, run the following command:

npx umbot create my-bot-project
Copy

After the command runs, the application is created, and all that is left is to run:

npm i
npm run build
npm start
Copy

A project with a JSON configuration

To quickly create an application with additional settings, follow these steps.

Create a config.json file

{
    "name": "quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "tokens": {
            "alisa": {
                "token": "..."
            },
            "telegram": {
                "token": "..."
            }
        }
    },
    "isEnv": true
}
Copy

⚠️ Security: fields such as tokens.*.token, db.host, db.pass, etc. in your JSON config are placeholder values. Do not keep real tokens in *.json (it will get into git); use .env or environment variables. The generated .env is automatically added to .gitignore, but if you create it manually, make sure .gitignore covers it.

Then run:

npx umbot create config.json
Copy

The utility creates a project in the ./bots/quiz folder with all the specified settings.

npm i
npm run build
npm start
Copy

⚙️ The configuration file (in detail)

Configuration file structure

When creating a project from JSON, you can pass the following parameters:

interface ProjectConfig {
    // Project name (required)
    name: string;

    // Project type: "default" or "quiz"
    type?: 'default' | 'quiz';

    // Mode: "prod", "dev", "dev-online", "build"
    mode?: 'prod' | 'dev' | 'dev-online' | 'build';

    // Application configuration (IAppConfig from umbot)
    // In the CLI this is an object merged with the template's default config.
    config?: Record<string, unknown>;

    // Platform parameters/intents (IAppParam from umbot)
    // In the CLI this is an object merged with the template's default params.
    params?: Record<string, unknown>;

    // Path where the project is created
    path?: string;

    // The host name the application runs on. Defaults to 0.0.0.0
    hostname?: string;
    // The port the application runs on. Defaults to 3000
    port?: number;
    // Move the tokens and database parameters from this JSON to the project's .env (without the flag they are removed from the configuration)
    isEnv?: boolean;
}
Copy

Configuration file example

{
    "name": "my-quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "db": {
            "host": "",
            "user": "",
            "pass": "",
            "database": ""
        },
        "tokens": {
            "alisa": {
                "token": "token"
            }
        }
    },
    "isEnv": true
}
Copy

⚠️ In the example above, tokens and database parameters are shown as placeholder strings. In a real project it is recommended to leave them empty in the config and fill them in .env, which the CLI creates in every project (it is already in .gitignore). With { "isEnv": true } the values from the JSON are moved to .env automatically.

Project types

Type	Description	Features
default	Basic template	A minimal project structure
quiz	Quiz template	A ready-made structure for building quizzes

Modes

Mode	What is generated in src/index.ts
prod	Bot in the strict_prod mode and bot.start() — a webhook server (the default if there is no mode)
dev	BotTest and bot.test() — a dialog in the console, without a server
dev-online	Bot in the dev mode and bot.start() — a server with detailed logs
build	Runs through run(config, mode) from umbot/build; the mode is switched with one line in the file

Creating a project from the visual editor (from-flow)

The create from-flow command creates an umbot project from a JSON file exported from Umbot Flow — the visual editor for the umbot framework.

The pipeline: visual editor → JSON configuration → npx umbot create from-flow → TypeScript project

A detailed description of the JSON format: src/docs/json-format.md

Usage

npx umbot create from-flow flow.json
npx umbot create from-flow flow.json --output ./my-bot
Copy

Parameters

Parameter	Description
flow.json	Path to the JSON file exported from the editor
--output ./path	Path for the output project (by default: the flow.json file name without extension)

The generated structure

my-bot/
├── src/
│   ├── index.ts              # Entry point with command registration
│   └── utils.ts              # setText/setTTS helper functions
├── package.json
├── tsconfig.json
├── README.md                 # How to install, fill in tokens, run and connect platforms
├── .env                      # Token variables for the chosen platforms (not committed)
└── .gitignore
Copy

The .env file is always created: the token variables for the chosen platforms are empty if flow.json has no tokens. On regeneration (--force), filled-in values are kept, missing variables are appended, and empty ones are filled with tokens from flow.json. The generated bot reads .env from the folder it is started in.

Command slots

String slots are generated in lower case: the user's utterance reaches the bot already lowercased, and a "Weather" slot from the editor would otherwise never match. Regex slots (isPattern) stay as they are — write them for lowercase text. More in the JSON format description.

Dialog start

The greeting (the welcome node, or the welcome text and buttons from the settings if there is no node) fires:

• on /start (Telegram, including with a deep-link parameter) and on the built-in Russian greeting slots ("hi"/"hello") or the node's own slots;
• at the beginning of a dialog without a command — a new Alice/Marusia session, "Start" in MAX/Viber (messageId === 0): in this case the fallback command calls the greeting.

A step that was waiting for an answer in the previous session skips the dialog start (return false). Without a greeting the start goes to the fallback. The bot mode (mode in flow.json) is generated as a bot.setAppMode(...) call right after Bot is created — before commands are registered. Without the mode field (or with an unknown value) strict_prod is generated.

Generation modes

• Simple (commands only): all the logic is generated in index.ts
• Complex (steps, conditions, variables): commands, steps and conditions are also generated as functions in index.ts; no separate controller file is created in either mode

Example workflow

1. Open the visual editor: flow.maxim-m.ru
2. Create a flow with commands, steps and conditions
3. Export the JSON configuration → download flow.json
4. Run: npx umbot create from-flow flow.json --output ./my-bot
5. Go to the project, fill in the platform tokens in .env and start it (details are in the generated README.md):

cd my-bot
npm install
npm run build
npm start
Copy

Best practices

1. Project naming:

   • Use clear names
   • Avoid spaces and special characters
   • Keep in mind: the CLI replaces all non-alphanumeric characters in the name with _ (npx umbot create my-bot creates the my_bot directory and the same name in package.json), so use snake_case or a single-word name

2. Configuration:

   • Keep the configuration in separate files
   • Do not include sensitive data in the repository
   • Use different configurations for different environments

3. Project structure:

   • Follow the recommended structure
   • Put files in the appropriate directories
   • Document non-standard decisions