CLI Commands

The AstrBot CLI initializes instances, starts AstrBot, updates common config values, and manages plugins.

If you install AstrBot with uv:

uv tool install astrbot --python 3.12

uv creates the astrbot executable and puts it on PATH. You can inspect the path with:

Linux / macOS

which astrbot

Windows

where.exe astrbot

TIP

Run the commands below from the AstrBot working directory.

Quick Start

Initialize the directory once, then start AstrBot:

astrbot init
astrbot run

astrbot init creates the data directories and configuration files required by AstrBot. After initialization, use astrbot run for later starts.

Top-Level Commands

Command	Purpose
astrbot init	Initialize the current directory as an AstrBot working directory.
astrbot run	Start AstrBot in the foreground.
astrbot conf	Read or update common config values.
astrbot password	Change the WebUI login password interactively.
astrbot plug	Create, install, update, remove, or search plugins.
astrbot help	Show CLI help.
astrbot --version	Show the AstrBot CLI version.

Start AstrBot

astrbot run

Common options:

Option	Purpose
-p, --port <PORT>	Set the WebUI port.
-r, --reload	Enable plugin auto-reload for plugin development.
--reset-password	Reset the WebUI initial password on startup and print the new password in startup logs.

Examples:

astrbot run --port 6185
astrbot run --reload
astrbot run --reset-password

If you forget the WebUI login password, run this from the AstrBot working directory:

astrbot run --reset-password

AstrBot regenerates the initial password during startup and prints it in startup logs. After logging in, change the password in the WebUI immediately.

When starting directly from source, you can also run:

python main.py --reset-password

Config

astrbot conf reads and updates common config values.

astrbot conf get
astrbot conf get dashboard.port
astrbot conf set dashboard.port 6185

Supported keys:

Key	Description
timezone	Time zone, for example Asia/Shanghai.
log_level	Log level: DEBUG, INFO, WARNING, ERROR, or CRITICAL.
dashboard.port	WebUI port.
dashboard.username	WebUI username.
dashboard.password	WebUI password.
callback_api_base	Callback API base URL. Must start with http:// or https://.

Changing the dashboard password writes the current password hashes automatically:

astrbot conf set dashboard.password "new-password"

You can also use the dedicated interactive password command:

astrbot password
astrbot password --username admin

Plugins

astrbot plug manages plugins under data/plugins.

Command	Purpose
astrbot plug list	List installed plugins.
astrbot plug list --all	Also show uninstalled plugins.
astrbot plug search <QUERY>	Search plugins.
astrbot plug install <NAME>	Install a plugin.
astrbot plug update [NAME]	Update one plugin, or all updatable plugins if no name is given.
astrbot plug remove <NAME>	Remove an installed plugin.
astrbot plug new <NAME>	Create a new plugin from the template.

Use a GitHub proxy when installing or updating plugins:

astrbot plug install example-plugin --proxy https://gh-proxy.example.com/
astrbot plug update --proxy https://gh-proxy.example.com/

Creating a new plugin asks for the author, description, version, and repository URL:

astrbot plug new my-plugin

Help

Show general CLI help:

astrbot help

Show help for a specific command:

astrbot help run
astrbot run --help
astrbot help conf
astrbot plug --help

Show the version:

astrbot --version