CLI Commands

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

If you install AstrBot with uv:

bash

uv tool install astrbot --python 3.12

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

::: code-group

bash

which astrbot

powershell

where.exe astrbot

:::

[!TIP] Run the commands below from the AstrBot working directory.

Quick Start

Initialize the directory once, then start AstrBot:

bash

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

bash

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:

bash

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:

bash

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:

bash

python main.py --reset-password

Config

astrbot conf reads and updates common config values.

bash

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:

bash

astrbot conf set dashboard.password "new-password"

You can also use the dedicated interactive password command:

bash

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:

bash

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:

bash

astrbot plug new my-plugin

Help

Show general CLI help:

bash

astrbot help

Show help for a specific command:

bash

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

Show the version:

bash

astrbot --version