Chat2DB CLI

English | French | Japanese | Spanish | Korean

Chat2DB CLI is the official command-line and agent integration toolkit for Chat2DB. It provides a Rust CLI for desktop lifecycle, datasource metadata, SQL, and MCP workflows, plus the Chat2DB Agent Skill in the same repository. Chat2DB Community is the default edition.

Included

• chat2db: a native CLI for macOS, Linux, and Windows.
• skill/: the Chat2DB Agent Skill for Codex and Claude Code.
• Machine-readable --json output for scripts and agents.
• One version and one release for the CLI and Skill.

Quick Start With Community

Install the CLI on macOS or Linux:

curl -fsSL https://github.com/OtterMind/Chat2DB-CLI/releases/latest/download/install-cli.sh | sh

On Windows PowerShell:

iwr https://github.com/OtterMind/Chat2DB-CLI/releases/latest/download/install-cli.ps1 -UseBasicParsing | iex

On macOS or Windows, install and inspect Chat2DB Community:

chat2db install --edition community
chat2db status

community is the default edition, so the explicit --edition community option may be omitted. Community is local-first and does not require login. On Linux, the CLI and Agent Skill are supported, while desktop lifecycle and runtime commands require a supported Chat2DB desktop release.

System Requirements

• macOS 11 or later on arm64 or x86_64.
• Windows 10 or 11, 64-bit only. Windows on ARM64 runs the x86_64 binary through the operating system's x64 compatibility layer. 32-bit Windows is not supported.
• GNU/Linux on arm64 or x86_64 with glibc 2.35 or later. Published Linux artifacts use GNU libc; musl-only systems, including Alpine Linux, are not supported.

Editions

Capability	Community	Pro	Local
Install and desktop lifecycle on macOS/Windows	Yes	Yes	Yes
Headless CLI runtime	Yes	Yes	Yes
Datasource CRUD and metadata	Yes	Yes	Yes
SQL execution	Yes	Yes	Yes
MCP management and tool calls	Yes	Yes	Yes
Account login and logout	Not applicable	Yes	Yes
JSON output	Yes	Yes	Yes

Community runtime, datasource, metadata, and SQL commands require a compatible Chat2DB Community 5.3.0 or later build. The CLI validates the runtime edition, API version, and capabilities before sending business data and fails closed on an incompatible server instead of falling back to Local or Pro.

Use --edition community, --edition pro, or --edition local to target one product. Commands that support multiple products also accept --edition all. Run chat2db <command> --help for the exact options available to a command.

CLI Workflows

Manage the Community desktop app:

chat2db status
chat2db start --edition community
chat2db stop --edition community
chat2db restart --edition community

The runtime, datasource, and SQL examples below require a compatible Chat2DB Community 5.3.0 or later build. An older or mismatched runtime is rejected before the CLI sends business data.

Inspect the local runtime:

chat2db runtime status --edition community --json
chat2db runtime start --edition community --json
chat2db runtime stop --edition community --json

List datasources and metadata:

chat2db db datasources --edition community --json
chat2db db databases --edition community --data-source-id 123 --json
chat2db db schemas --edition community --data-source-id 123 --database postgres --json
chat2db db tables --edition community --data-source-id 123 --database postgres --schema public --json
chat2db db table --edition community --data-source-id 123 --database postgres --schema public --table users --json

Test and create a datasource:

chat2db db connection-test --edition community --db-type MYSQL --host 127.0.0.1 --port 3306 --database demo --user root --password '<password>' --json
chat2db db datasource-create --edition community --db-type MYSQL --host 127.0.0.1 --port 3306 --database demo --user root --password '<password>' --environment-id 1 --json

Prefer reusing a saved datasource so a password does not enter shell history. Never publish passwords, tokens, private hosts, or production data in logs or issues.

Run SQL:

chat2db sql query --edition community --data-source-id 123 --database postgres --schema public --sql 'select 1' --json

The CLI starts or reuses the selected edition's loopback-only runtime when a database command needs it.

MCP

Enable MCP, inspect its tools, and print a client configuration:

chat2db mcp enable --edition community --json
chat2db mcp tools --edition community --json
chat2db mcp config --edition community

Call a tool directly:

chat2db mcp call list_all_datasources --edition community --args-json '{}' --json

mcp config intentionally contains an authentication token. Treat its output as a secret and do not paste it into public logs.

Agent Skill

Install the bundled Skill for Codex:

chat2db skill install --client codex

Or for Claude Code:

chat2db skill install --client claude-code

Update or remove it with:

chat2db skill update --client codex
chat2db skill uninstall --client codex

The Skill is maintained in skill/ and released with the matching CLI version. It uses the CLI instead of duplicating Chat2DB runtime logic.

Automation

At startup, interactive commands with human-readable output perform a best-effort update check. The network manifest is refreshed at most once every 24 hours; other starts reuse the private cache and continue to show a known newer version. The check only prints a notice and never installs automatically. It is skipped for --json, non-interactive sessions, background processes, and the update, completions, and logs commands. Set CHAT2DB_NO_UPDATE_CHECK=1 to disable it.

Use --json when output is consumed by a script or agent:

chat2db status --json
chat2db version --json

Mutating or destructive commands may require --yes. Supported operations can be inspected with --dry-run. JSON responses never intentionally expose datasource passwords or runtime bearer tokens.

Install From Source

Install the stable Rust toolchain, then run:

git clone https://github.com/OtterMind/Chat2DB-CLI.git
cd Chat2DB-CLI
cargo build --release
cargo test

The binary is written to target/release/chat2db (or target/release/chat2db.exe on Windows). The default developer command builds with the lockfile and transactionally installs both the CLI and the Codex Skill. Use the second form for Claude Code or the third to refresh only the Codex Skill:

bash scripts/dev-install.sh
bash scripts/dev-install.sh --client claude-code
bash scripts/dev-install-skill.sh --client codex

These development installers require Bash. On Windows, run them from Git Bash, MSYS2, or Cygwin; a native PowerShell development installer is not provided. The combined command commits the CLI and Skill together, restores both after a failed or interrupted install, and requires --force before taking ownership of targets that do not have matching installer provenance.

Development

Before opening a pull request, run:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

When CLI behavior or commands change, update the Skill and all five README files in the same pull request. See CONTRIBUTING.md.

Repository Layout

src/          Rust CLI
tests/        integration tests
skill/        Chat2DB Agent Skill
scripts/      local install and packaging helpers
.github/      CI and release automation

Releases

The manually dispatched release workflow has two modes. cdn-only builds and uploads immutable versioned objects without changing latest. release requires a pre-existing signed vX.Y.Z Tag at the protected main HEAD, then promotes CDN aliases and publishes the CLI binaries and Skill bundle together to GitHub Releases.

Each GitHub Release includes a CycloneDX SBOM and GitHub build-provenance attestation. Every CLI and Skill archive includes LICENSE and THIRD_PARTY_LICENSES.txt; both files are also top-level Release assets. CDN credentials and the Feishu notification webhook are held only in GitHub Actions secrets; they are never stored in this repository. Maintainers should follow docs/RELEASING.md.

CLI and Skill installers read authoritative manifests from GitHub Releases; those independently hosted manifests pin the checksum of each CDN artifact. Desktop install metadata is reviewed in desktop-artifacts.json and compiled into the CLI. Community entries pin formal GitHub Release assets with SHA-256; Pro and Local entries pin exact versioned CDN artifacts with size and Base64 SHA-512. The CLI never trusts a mutable CDN update manifest at install time. Update the CLI to obtain a newer reviewed desktop artifact registry.

Security

Do not report vulnerabilities in public Issues. Follow SECURITY.md and use GitHub private vulnerability reporting. Chat2DB Community is a single-user, local-first product; do not expose its local service directly to untrusted networks.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md and follow the Code of Conduct.

License

The CLI and Agent Skill in this repository are licensed under the Apache License 2.0. This repository's license is independent from the license applied to the Chat2DB Community server source.