vbot-cli

vBot CLI

The vbot CLI is the automation surface for configuring and operating a vBot instance: run the command, verify the result, report what changed. One async Runtime lives behind the server; the CLI, WebUI, Desktop, and Channels are Accessors to that same system rather than separate stores.

System and paths

Keep these boundaries separate:

• vbot_root is the checkout or installation containing vBot code and bundled resources.
• data_dir is the server instance's local runtime state and credentials. ~/.vbot is only the product default, not a path to assume.
• A Project cwd is the external working directory where file and shell Tools operate for that Project; it is referenced by Project state but is not contained by the data directory.
• An Identity Agent's Workspace is its identity and Memory home. It defaults inside the Agent's data directory but may be configured as an external absolute path.
• A Session is persisted conversation history owned by one Agent; a Run is one active execution inside it and is not a separate top-level data directory.

Run vbot home before local filesystem investigation to resolve vbot_root and data_dir. The command reports the machine where it runs and does not query a server selected with --host; when targeting a remote vBot server, use its CLI/RPC diagnostics unless you separately have filesystem access to that server host.

Read references/system-layout.md before searching runtime files, diagnosing missing or corrupt stored state, making an unavoidable manual edit, or planning a data backup, move, or reset. Use the owning CLI area first and inspect files only when the semantic command cannot answer the question.

Rules

• Primary identifiers are positional (vbot agent show assistant); secondary parameters are flags. vbot <area> <command> --help shows exact flags plus a usage example.
• Only server start|stop|restart|status, desktop, update, uninstall, autostart, and doctor work without a running target server. Everything else needs one. When operating the vBot instance hosting the current Run, execute the requested command directly — the Run already proves that server is available. Check vbot server status and start with vbot server start only when targeting another instance or troubleshooting connectivity.
• Non-default instance: add --host, --port, --data-dir to every command.
• Prefer CLI commands over direct file edits — settings, agents, channels, cron jobs, Bootstrap jobs, prompt blocks, and provider keys all have commands. If a manual JSON edit was unavoidable, validate with vbot doctor config.
• Before vbot update when it will restart the server, arm and verify a one-shot Bootstrap in the current Session so the Run resumes after startup and checks the result. Follow references/server.md; do not create one for --no-restart unless the user separately wants a later-startup check.
• Never echo secrets in output. API keys go through provider set-key, extension secrets through extensions <name> set <field> --stdin, and managed channel tokens through channel add ... --token-stdin or channel set-token ... --stdin. Channel tokens never belong in shell arguments; use --token-env only when an external deployment environment already owns the variable.
• Inspect before changing; verify after with the matching list/show/status command. For Settings, discover paths with vbot config list [prefix], inspect type/default/lifecycle with vbot config describe <path>, then verify the effective result with vbot config get <path> --details.
• Treat vbot model show and vbot task-model options as authoritative for Model capabilities, voices, and accepted Task Model values. Never infer one Model's options from another Model or from generic provider documentation.
• Mutation output is a verification result, not merely an acknowledgement: Agent, Project, Channel, Cron, and Bootstrap create/update commands print the saved resource; Project removal prints affected rooted Agents and file-copy/backup effects. Read it before issuing a separate verification call, then use show/list when the requested outcome depends on live discovery or runtime health.
• Keep Identity Agent, Project Agent, Workspace, and Project cwd separate. A generic request to create an Agent means an Identity Agent; root it in a Project when its file/shell work should run there. A Project Agent is a repo-discovered Config Agent with no Workspace, SOUL, or Memory and is created only when the user explicitly asks for a Project Team profile. See references/agents-projects.md.
• Follow CLI error hints (did you mean, candidate lists) before retrying. If another process occupies the port, report it — don't kill it.
• Finish with a compact report: commands run, what changed, verification result, and any remaining user action (complete an OAuth login, send a Telegram message, ...).