mysql-shared

mysql-cli Shared Rules

CRITICAL: This skill is referenced by mysql-query and mysql-schema. Read this file with the Read tool before using either.

mysql-cli is a Go CLI that lets any shell-capable AI agent query MySQL without an MCP runtime. It is a drop-in replacement for designcomputer/mysql_mcp_server, re-exposing all read/write capabilities as plain subcommands with JSON by default and stable exit codes. Agents are the primary caller; the REPL is only for human debugging.

Convention: assume the mysql-cli binary is on PATH. If not, install with go install github.com/AllenMuu/mysql-cli/cmd/mysql-cli@latest or point commands at the built binary.

---

Before Running

Run these checks before the first command in a session. They are cheap and prevent the most common failures (missing config, unreachable datasource).

1. Config file exists

ls ~/.config/mysql-cli/config.toml

If missing, mysql-cli still works via MYSQL_* env vars or --host/--port/... overrides, but a config file is the normal path. Resolution priority is CLI flag > env > project-level (trusted) > global > default (see Project-level Config below). Passwords support ${ENV} placeholders (expanded only in trusted configs).

2. Datasource reachable

A lightweight probe via the read-only databases command (no table scan):

mysql-cli databases -f json

• Exit 0 + {"success":true,...} -> reachable, proceed.
• Exit 2 (CONN_FAILED) -> check host/port/credentials/SSH tunnel.
• Exit 10 (CONFIG_ERROR) -> check config.toml syntax or datasource name.

3. (Optional) Pick a datasource

If the config defines multiple [datasource.<name>] profiles, select one with -d <name>. Otherwise the default entry is used.

---

Project-level Config

mysql-cli supports project-level config, structurally identical to the global config and merged override-style (similar to MCP's .mcp.json).

• Project-level config location: <project-root>/.config/mysql-cli/config.toml. Discovered by walking up from cwd; the first match wins (stops at home/fs root). Shares the relative path .config/mysql-cli/config.toml with the global ~/.config/mysql-cli/config.toml; only the root differs.
• Trust mechanism (security): project-level config is not loaded by default. First run mysql-cli config trust --yes inside the project directory to write the project root into the trust list at ~/.config/mysql-cli/trusted. config trust requires --yes in non-interactive mode (or an interactive y/N prompt on a TTY) -- AI agents must NOT auto-trust; a human decides. When untrusted, it falls back to global (exit 0) and prints a stderr WARN naming the skipped project config (the warning deliberately omits the trust command, to avoid AI auto-trusting). Suppress with --no-trust-warn or MYSQL_CLI_NO_TRUST_WARN=1; escalate to a hard error with --strict-trust. ${ENV} password placeholders expand only in trusted project-level configs - preventing malicious repos from harvesting local env vars or hijacking connections.
• Priority chain: --config flag > MYSQL_CLI_CONFIG env > project-level (trusted) > global > MYSQL_* field-level overrides > default. When --config or MYSQL_CLI_CONFIG is set, only that file is read and auto-discovery is skipped.
• Override-style merge: same-named datasources replace wholesale (project wins, including SSH subtables); different names form a union; default and default_limit from project override global.