@codebolt/client-cli

Command-line client for interacting with a running CodeBolt server from scripts, terminals, CI jobs, and local development workflows.

The CLI wraps the CodeBolt client SDK and exposes high-level commands for chat, agents, projects, tasks, memory, knowledge, browser automation, MCP servers, and other CodeBolt server resources.

Installation

Install globally:

npm install -g @codebolt/client-cli

Run without a global install:

npx @codebolt/client-cli --help

After installation, the executable is:

codebolt-client --help

Requirements

Node.js 20 or newer is recommended.
A running CodeBolt server that exposes the client HTTP and WebSocket APIs.
Network access from your terminal to the server host and port.

By default, the CLI connects to:

localhost:12345

You can override this with --host, --port, or the SOCKET_PORT environment variable.

Global Options

These options are available on the root command and apply to subcommands:

-p, --port <number>   Server port. Defaults to SOCKET_PORT or 12345.
-H, --host <string>   Server hostname. Defaults to localhost.
--json                Emit machine-readable JSON where supported.
--debug               Enable debug logging.
--timeout <ms>        HTTP timeout in milliseconds. Defaults to 30000.

Example:

codebolt-client --host 127.0.0.1 --port 12345 --json project info

Quick Start

Check the CLI:

codebolt-client system check-cli

Send a chat message and wait for completion:

codebolt-client chat send --message "Summarize the current project"

Send a chat message with streamed output:

codebolt-client chat send-streaming --message "Create a task plan for this bug"

List installed agents:

codebolt-client agent list

Get current project information:

codebolt-client project info

Command Groups

Use codebolt-client help <command> for command-specific options.

Command	Purpose
`chat`	Send messages, stream responses, manage threads, and store chat messages.
`agent`	List, install, start, stop, update, and inspect agents.
`execution`	Inspect agent executions and execution trees.
`git`	Run CodeBolt-backed git operations such as status, diff, commit, branch, push, pull, and clone.
`task`	Create, update, list, delete, and inspect tasks.
`project`	Read and update project context, active project, threads, and chat history.
`workspace`	List, inspect, and select workspaces.
`llm`	List providers and models, update keys, set defaults, and inspect local model state.
`memory`	Manage generic, markdown, JSON, context, and episodic memory.
`knowledge`	Manage knowledge collections, documents, URLs, and strategies.
`swarm`	Create, start, stop, inspect, and manage swarms, teams, roles, and swarm agents.
`env`	Manage environments and environment providers.
`job`	Create, update, list, delete, and inspect jobs.
`actionblock`	List action blocks, inspect details, stop executions, and view stats.
`browser`	Navigate, click, fill, screenshot, and send browser automation actions.
`mcp`	List, inspect, configure, toggle, and install MCP servers.
`file`	Check for files and add file content through the CodeBolt server.
`system`	Check or install CLI-related system state.

Common Examples

List chat threads:

codebolt-client chat threads list

Create a task:

codebolt-client task create --title "Investigate failing build" --priority high

Update a task:

codebolt-client task update task_123 --status in-progress

Show git status:

codebolt-client git status

Create a git commit:

codebolt-client git commit --message "Fix client CLI package metadata"

Navigate the browser:

codebolt-client browser navigate --url "http://localhost:3000"

Configure an MCP server from JSON:

codebolt-client mcp configure --data "{\"name\":\"local-server\",\"enabled\":true}"

JSON Output

Use --json for automation and scripts:

codebolt-client --json task list --status open

For commands that return structured data, the CLI writes JSON to stdout. Errors are written in a consistent error format where supported.

Chat Completion Output

chat send and chat send-streaming connect to the CodeBolt chat WebSocket endpoint and wait for the agent process to finish.

When the server provides debug information, completion output can include:

Thread ID
Project path
Thread chat path
Debug log paths
Child agent execution details

Use --timeout on chat commands for long-running agent work:

codebolt-client chat send --message "Run the full review" --timeout 900000

Local Development

This package is built from the codeboltjs checkout and uses local sibling packages from the main CodeBolt checkout:

../../CodeBolt/packages/types
../../CodeBolt/sdks/clientsdk

Install dependencies:

npm install

Build the CLI and its local SDK/type dependencies:

npm run build

Build only the CLI bundle:

npm run build:local

Type-check without emitting files:

npm run typecheck

Create a local npm tarball preview:

npm pack --json --ignore-scripts

Publishing

The package publishes the bundled dist output and the executable in bin.

Before publishing:

npm install
npm run build
npm pack --json --ignore-scripts

Publish publicly:

npm publish --access public

Troubleshooting

npm install returns 404

If the npm website shows the package but npm install returns 404, check that npm is using the public registry:

npm config get registry
npm config get @codebolt:registry

Force the public registry for one install:

npm install -g @codebolt/client-cli --registry=https://registry.npmjs.org/

If the package was just published, npm registry propagation can briefly lag behind the website. Retry after a few minutes.

Cannot connect to the server

Verify the CodeBolt server is running and that the CLI is using the correct host and port:

codebolt-client --host localhost --port 12345 system check-cli

Commands need JSON payloads

Many commands accept JSON through --data. Quote JSON according to your shell. In PowerShell:

codebolt-client job create --data '{\"title\":\"Build package\",\"status\":\"open\"}'

License

MIT

GeezerVison

Expand file tree

codebolt-client-cli

Directory actions

More options