mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-16 01:40:15 +08:00

Files

Soulter 53296fcc73 fix(docs): restore cli command pages

2026-06-16 23:47:30 +08:00

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:

::: code-group

which astrbot

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.

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.

astrbot run

Common options:

Option	Purpose
`-p, --port <PORT>`	Set the WebUI port.
`-r, --reload`	Enable plugin auto-reload for plugin development.

Examples:

astrbot run --port 6185
astrbot run --reload

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

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

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