Command Line Interface (CLI)

A comprehensive, interactive developer tool to manage your Telegram-backed database, test server endpoints, and transfer large assets directly from your command prompt.

Document Summary

What it does

Registers the global binary command telebase on your local computer to authenticate projects, query tables, and transfer binary storage chunks.

When to use it

For setting up local developer environments, running test SQL queries, scripting backups, or building automation file pipelines.

Key command

npm install -g telebase-cli to install globally, followed by telebase init to link your project.

1. Global Installation

Telebase CLI is distributed publicly on the npm registry as a globally executable utility. You can install it on any system running Node.js (version 18+ recommended):

npm install -g telebase-cli

2. Global Flags

Use the following options to verify the CLI version and display help menus:

telebase --version / -V

Outputs the currently installed version number of the Telebase CLI package.

telebase --help / -h

Displays a complete layout of all available commands, options, and parameters directly inside your terminal.

3. Project Link & Initialization

Connect your terminal to your serverless backend instance by running the interactive config command:

telebase init

The CLI will prompt you for the **Telebase API Server URL** (press enter to default to the official https://telebase.pages.dev) and your project's unique **API Key**. These configurations are saved locally in a .env file within your working directory.

4. Command References

telebase status

Ping Test

Pings your deployment server to check if it's active. If successful, it returns the server status and lists the total number of tables created in the project:

$ telebase status
✔ Connected successfully! Telebase server is online.
ℹ Tables registered in project: 4

telebase query <sqlQuery>

Database SQL

Execute any standard relational SQL queries (SELECT, INSERT, UPDATE, DELETE, etc.) directly on your database. If records are returned, the CLI formats the output into a clean, aligned console table:

$ telebase query "SELECT name, age, plan FROM users LIMIT 3"
✔ Query executed successfully!
┌─────────┬──────────┬──────┬──────────────┐
│ (index) │   name   │ age  │     plan     │
├─────────┼──────────┼──────┼──────────────┤
│    0    │ 'Aman'   │  23  │ 'enterprise' │
│    1    │ 'Emma'   │  28  │   'basic'    │
│    2    │ 'Rohit'  │  21  │   'student'  │
└─────────┴──────────┴──────┴──────────────┘

telebase upload <filePath>

File Hosting

Upload files of any size directly. The CLI automatically compresses, encrypts (if enabled), splits large files into 19MB packets to comply with Telegram API bot constraints, and outputs a unique **Asset UUID**:

$ telebase upload ./archive.zip
ℹ Reading file: archive.zip...
ℹ Uploading to Telegram storage channel...
✔ File uploaded successfully!
ℹ File Name: archive.zip
ℹ File Size: 42.50 MB
ℹ Asset UUID: 96aec088eb7e4f7032683ba7d129169cb8f94f7954b696886fc5dcc6fa2fe4e3
ℹ Retrieve URL: https://telebase.pages.dev/api/data/download?uuid=96aec088eb7e4f7032683ba7d129169cb8f94f7954b696886fc5dcc6fa2fe4e3

telebase download <uuid> [outputName]

File Retrieval

Downloads, decrypts, and merges chunked files back to your local folder by their unique asset UUID. If an optional [outputName] parameter is provided, the file will be saved with that filename; otherwise, it resolves the original filename automatically:

$ telebase download 96aec088eb7e4f7032683ba7d129169cb8f94f7954b696886fc5dcc6fa2fe4e3
ℹ Fetching file details for UUID: 96aec088...
✔ File downloaded and saved to: D:\projects\archive.zip

telebase diagnose

Diagnostic Check

Performs a complete diagnostic evaluation of your CLI local environment. It checks Node.js compatibility, verifies the existence of your local .env file, validates required project parameters, measures server latency, performs a mock SQLite/database call, and queries the NPM registry to verify if you are on the latest version of telebase-cli:

$ telebase diagnose

⚡ Telebase Environment Diagnostics

ℹ Node.js Version: v20.11.0
✔ Node.js version is compatible.
ℹ Checking configuration in: D:\projects\.env
✔ Local .env file exists.
✔ Required environment variables are set.
ℹ Pinging API server: https://telebase.pages.dev...
✔ Server is online and responding (Latency: 124ms).
✔ Database query engine is functioning correctly.
ℹ Checking for updates from npm registry...
✔ You are running the latest version of telebase-cli (1.0.0).
ℹ Diagnostics complete!

5. CLI Development & Publishing Commands

If you are contributing to Telebase CLI or linking it locally for development, use these packaging commands:

Local Project Linking

Build and globally register the CLI binary dynamically on your development machine:

cd cli
npm install
npm link

Publishing to Public Registry

Publish your updated CLI version to the public npm package repository (requires 2FA credentials or a registered browser passkey):

npm login
npm publish --access public