CLI in the terminal

geckochat is your cabinet as commands. The same operations on the same projects and bots, from a terminal: in a script, in CI, over SSH, in any session that has a key.

Install

curl -fsSL https://api.geckochat.app/cli/install.sh | bash

The installer detects your system and processor, downloads the matching file, verifies its checksum and puts the program into /usr/local/bin (or ~/.local/bin if that is not writable). No Node, no Bun, no sources required.

The key, once

geckochat login gk_YOUR_KEY

login checks the key against the server first and only then remembers it on this machine, in a file readable by your user alone. A wrong key is never saved — you find out right away, not at the first real command.

After that the connection can be checked any time: geckochat whoami answers with the address and the number of available commands.

First commands

geckochat --help                 # everything the platform can do
geckochat --help broadcast       # only broadcasts
geckochat project_list --table id,name
geckochat bot_list --table id,username,usersCount,status
geckochat user_list --projectId <project> --limit 5
geckochat bot_get --help         # the arguments of one command

Commands are the platform's own tools, not a separate list: a new capability appears in your terminal together with the server, without updating the program.

The project and the bot in a command

The key is you, so every command names what it works with:

• The project — --projectId <project>. project_list shows its identifier. Commands about users, broadcasts, orders, offers, sites and the agent work this way.
• The bot — --botId @YourBot: a bot is named the way it is in Telegram. Its internal identifier (bot_list shows it) works too, but you do not need to remember it. The bot is required by commands about a person's chat in one channel (user_chat_suggest, user_chat_mark, user_chat_exec_flow, user_block, user_unblock) and narrows the choice where it is optional: user_list --botId @YourBot lists the people of one channel. When a bot is named, the project follows from it and --projectId is not needed.
• The person — --userId <id>: the identifier of the user from the first column of user_list. A Telegram ID does not work in its place.

geckochat user_list --projectId <project> --limit 5 --table id,firstName
geckochat user_chat_timeline --userId <id> --botId @YourBot

A bot is named the same way in every command: @YourBot, YourBot or the identifier. The bot must belong to the command's project: an unknown name and a bot of another project get the same BOT_NOT_FOUND refusal. The exception is the commands that detach, restart or delete a bot: they need the identifier from bot_list, so a renamed bot is never hit by mistake.

The server counts, not you

Questions like «how many», «which ones» and «for what amount» don't need an export:

geckochat bot_list --count-by status
geckochat broadcast_list --projectId <project> --count-by status
geckochat order_list --projectId <project> --limit 100 --sum amount --by currency
geckochat bot_list --top 5 --sort usersCount --table username,usersCount,status

--count-by counts records per value, --sum … --by totals with a breakdown, --sort and --top keep the leading ones, --table prints only the columns you asked for. Without these flags the full answer is printed, and --json puts it on one line — for scripts and jq.

Updating

geckochat update --check    # what the server has
geckochat update            # install it over itself

geckochat never updates itself: it only says, in one line, that a newer version exists. A tool that changes itself in the middle of a nightly script is the worst thing that can happen to a nightly script.

Next