Chat2db CLI

Chat2DB CLI

Use the chat2db command directly. Prefer live command output and chat2db <command> --help over static examples.

Start Here

command -v chat2db && chat2db version --json
chat2db status --json

If chat2db is missing, do not install it silently. Tell the user the appropriate install command from references/installation.md.

This Skill supports CLI versions >=0.2, <0.3. Outside that range, say that the Skill may be stale and continue from chat2db --help and chat2db <command> --help.

Edition Selection

• Use community when the user does not specify an edition.
• Use pro or local only when the user requests that product or the current state clearly belongs to it.
• Use all only for commands that explicitly support it. The order is Community, Pro, then Local.
• Community has no account authentication. login and logout with --edition community return not_applicable and must not open an authentication flow.

Community runtime, db, 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. Report any contract error; never retry against Local or Pro.

Read references/editions.md for the complete edition matrix and paths.

Priority

1. Run chat2db status --json before choosing follow-up commands. Read data.summary.<edition>, safe_to_exit, and next_action.
2. Prefer chat2db runtime, chat2db db, and chat2db sql for database work. These commands may start the headless runtime but should not open the GUI.
3. Start, install, stop, or restart the desktop app only when the user asks for that lifecycle action.
4. Use chat2db mcp only for an explicit MCP request or when direct runtime/database/SQL commands cannot perform the task.
5. Use --json whenever command output will be parsed.

Common Commands

Read references/commands.md for complete command shapes and flags.

Datasource Flow

1. List existing datasources for the selected edition.
2. Test user-supplied connection fields before creating a datasource when the password is non-empty.
3. Use either --url or --host --port --database; do not mix them.
4. Keep --password present for datasource creation, including an explicitly empty password.
5. Create only after a successful connection test, except for an intentionally empty-password datasource that cannot use the temporary test form.
6. Treat environment ids as 1=TEST and 2=RELEASE; default to 1 when the user does not specify one.

SQL Flow

1. Use --page-no and --page-size for result paging.
2. If hasNextPage is true, rerun the same SQL with the next page number.
3. Use --result-set-id for a specific result from multi-result SQL.
4. Use --no-row-number when downstream consumers need only database columns.

Safety

• Parse ok, data, error.code, error.details, error.hint, error.next_action, error.retryable, and error.risk. Do not branch on prose messages.
• Do not pass --json to chat2db logs; it streams log text.
• Run login only when explicitly requested. Never turn a Community not_applicable result into a Pro or Local login attempt.
• Do not install a missing edition unless the user asked for installation.
• Use --dry-run --json for writes with unclear impact. Use --yes only for explicit destructive intent.
• Do not retry an unchanged command when error.retryable is false.
• Do not auto-retry integrity, official-source, or unsafe-path errors.
• Poll long operations once or twice, then report their state.
• Redact passwords, tokens, cookies, and bearer values from user-facing output.
• chat2db mcp config intentionally includes a selected edition's MCP token; show it only when the user explicitly requests MCP client configuration.

References

Read a reference only when the live command help is insufficient.