CLI Reference

Starting a service, installing plugins, changing configuration, sending a message to a running bot -- daily interaction with zhin.js basically comes down to the single zhin command. It is provided by @zhin.js/cli; for creating a new project from scratch, use pnpm create zhin-app (a separate create-zhin-app package, not covered on this page).

zhin --help        # View all commands

Commands are roughly grouped into five categories: runtime with runtime / stop; plugin development with new, build, pub, install / add, uninstall, search, info, packages; configuration and diagnostics with setup, onboard, config, doctor, migrate; commands targeting running instances with send, watch, schedule, agent; and system services with service. Each is detailed below.

runtime: Run and Manage Projects

zhin runtime start [--mode production] [--no-watch] [--daemon]
zhin runtime init [package-name]
zhin runtime create <plugin|feature> <name> [package-name]
zhin runtime inspect
zhin runtime build
zhin runtime publish [--execute|--resume] [--tag latest]
zhin runtime migrate [extract|cutover|status] [--check|--write]

start is the entry point for starting a bot, supporting dev hot reload, production, daemon modes, and more. See zhin runtime start for details. The other subcommands each serve a specific purpose: init / create scaffold convention-based Plugin Runtime projects and plugin/feature packages; inspect outputs the project structure as JSON (plugin manifest, build plan); build / publish build and publish according to the project graph. publish only prints the plan by default; --execute actually runs it (supports --resume after interruption); migrate generates and applies project structure migration plans. --check only shows the plan, --write atomically writes changes, and status outputs a readiness report.

Conventional scripts in projects (generated by the scaffolder):

{
  "scripts": {
    "dev": "zhin runtime start",
    "start": "zhin runtime start --mode production --no-watch"
  }
}

stop: Stop the Bot

zhin stop

Stops the process started in daemon mode under the current project (reads .zhin.pid). If no running process is found, it simply displays a message without erroring.

new: Create a Plugin

zhin new [plugin-name] [--type normal|service|adapter] [--is-official] [--skip-install]

Generates a convention-based plugin package template under plugins/<name>/. The plugin name must match /^[a-z][a-z0-9-]*$/. Without arguments, it enters interactive prompts (name, type).

build: Build a Plugin

zhin build [plugin] [--clean] [--production] [--analyze]

plugin is the path relative to plugins/ (e.g., adapters/icqq); when omitted, it builds the current package within a plugin directory, or batch-builds plugins/* from the workspace root. The build automatically compiles src/ (tsc) and client/ (esbuild) based on directory structure; --clean clears lib/ and dist/ first; --production (on by default) minifies client output.

pub: Publish a Plugin

zhin pub [plugin-name] [--tag latest] [--access public] [--registry <url>] [--dry-run] [--skip-build]

Run from the project root that contains a plugins/ directory; without a name, it interactively selects from publishable plugins. --dry-run runs through the flow without actually publishing.

install / add: Install a Plugin

zhin install <plugin-name-or-git-url> [--no-enable] [--dry-run]
zhin add ...          # Alias for install

Option	Description
-S, --save	Write to dependencies (default)
-D, --save-dev	Write to devDependencies
-g, --global	Install globally (does not enable the plugin)
--no-enable	Only install the dependency, don't modify configuration
--dry-run	Print the install and configuration changes that would be made, without writing

The default behavior is to install via pnpm and then automatically write the plugin into zhin.config.yml under plugins.<instanceKey>, and add it to the zhin.plugins manifest in package.json. After installing an adapter, follow the prompt to run zhin setup --adapters to add Endpoints.

uninstall: Uninstall

zhin uninstall plugin <name> [--remove-pkg]
zhin uninstall adapter <name> [--remove-pkg]
zhin uninstall service

name can be an npm package name or an instanceKey; --remove-pkg also removes the dependency from package.json. uninstall service uninstalls the system service.

search / info: Discover Plugins

zhin search [keyword] [-c utility|service|game|adapter|admin|ai] [-l 20] [--official]
zhin info <package>

Search the plugin marketplace / view details of a specific plugin.

packages: Skills/Extension Packages

zhin packages install <npm:pkg|git:url> [--local]
zhin packages remove <name> [--local]
zhin packages list [--local]
zhin packages update [source] [--local]

Manage zhin-package skill/extension packages (ADR 0010); --local (-l) installs to the project's .zhin/packages/ instead of globally.

setup: Interactive Configuration Wizard

zhin setup                 # Full wizard
zhin setup --database      # Configure database only
zhin setup --adapters      # Configure adapters only (write endpoints)
zhin setup --ai            # Configure AI only
zhin setup --bootstrap     # Generate bootstrap files only (SOUL.md / TOOLS.md / AGENTS.md)
zhin setup --global        # Initialize a global instance in ~/.zhin

The wizard modifies the corresponding sections of zhin.config.yml, and writes secrets to .env. For a network database, it validates the port range, stores environment references in the config, and writes the actual values to .env. Run npx zhin config check afterward to find missing database variables before startup. For .env.production, use npx zhin config check --environment production.

onboard: Project Onboarding

zhin onboard [--quick] [--flow quickstart|full]

Reuse existing configuration / environment variables / data within the project, and choose to keep or reconfigure. --quick (-q) shows only the quick start without entering the wizard; --flow defaults to full, while quickstart asks fewer questions.

config: Read and Write Configuration Files

zhin config list
zhin config get <key>            # Supports nested paths, e.g., ai.enabled
zhin config set <key> <value>    # value supports JSON
zhin config delete <key>
zhin config path                 # Display the configuration file path
zhin config check [--fix] [--json] [--strict]

config check validates the configuration file and can automatically fix safely migratable fields. Missing database connection variables are errors; --strict promotes other warnings to errors (suitable for CI).

doctor: Environment Diagnostics

zhin doctor [--fix] [--upgrade-l4]

Checks system environment and project configuration; --fix automatically repairs fixable items; --upgrade-l4 diagnoses the minimal-to-L4 upgrade path (AI stack + optional peer).

migrate: Project Upgrade

zhin migrate [--dry-run] [--no-install]

Upgrades an older Zhin project to the latest version (dependencies, scripts, directory structure). --dry-run only prints the plan; --no-install skips the final pnpm install.

send: Send a Message to a Running Bot

zhin send <scene_id> [content...] [-s private|group|channel] [-a <adapter>] [-e <endpoint>]

Delivers a message via HTTP API to a daemon-running instance (requires HTTP service enabled). scene_id is the user ID for private chats or the group number for group chats; when content is omitted, one line is read from stdin. -a defaults to process; -e specifies the Endpoint ID, defaulting to the first online Endpoint under that adapter.

watch: Monitor a Running Instance

zhin watch [-i 3] [--once] [--json] [--no-clear]

Polls the Host API (stats / bots / assistant jobs) to refresh the dashboard; --once fetches once and exits, --json is suitable for scripts.

schedule: Persistent Scheduled Tasks

Tasks are stored in data/schedule-jobs.json; changes require a restart to take effect.

zhin schedule list
zhin schedule add "0 0 9 * * *" --prompt "Good morning, report today's schedule" [--kind solar|lunar|workday|freeDay]
zhin schedule add --every 30m --prompt "Check RSS"
zhin schedule add --at 2026-08-01T09:00:00Z --prompt "One-time reminder"
zhin schedule remove <id>
zhin schedule pause <id>
zhin schedule resume <id>

add options: --prompt (required, the prompt sent to AI when triggered), -l/--label, --kind (default solar), --notify-channel im|silent|log (default silent), --at (one-time ISO8601), --every (e.g., 30m, 1h, 1d). Choose one of cron, --at, or --every.

agent: Agent Authoring Diagnostics

zhin agent info [--json]

Lists discovered Agent capabilities and named Agents (Tools, Skills, Hooks, and related assets). Requires the AI stack to be installed (@zhin.js/agent + zod + ai).

service: System Service

zhin service install [--user]
zhin service uninstall [--user]
zhin service status [--user]

Install auto-start / daemon service; --user uses user-level systemd on Linux. status is available on Linux/macOS only.

Exit Codes

Exit Code	Meaning
51	Console requested a restart (CLI daemon automatically starts a new process)
75	Runtime reported restartRequired (e.g., lockfile changes); daemon restarts with storm protection policy

For process model and hot reload semantics, see zhin runtime start in Detail.