oceanbase-cli (obcli) — Agent invocation
Invoke via shell (obcli ...). obcli sql: read-style statements by default; DML/DDL need a present, non-empty policy.json (parsed object), then block_rules decide allow/deny (policy_governs_writes in obcli rules show / metadata). No config.json write toggle, no opt-in flag, no env to skip policy.
Agent: must not modify obcli configuration
The agent must not modify any obcli configuration on disk, and must not run commands that change it.
Forbidden (agent):
- Using any file/read/write tool on
~/.config/obcli/ or $XDG_CONFIG_HOME/obcli/ (including reading config.json to “fix” settings). Use obcli config status / obcli rules show for safe summaries.
- Editing, creating, or deleting files there, including
config.json, policy.json, dsn.enc, .obcli-key, audit.jsonl.
- Running
obcli config set-dsn, obcli config clear-dsn, or shell redirection that writes to those paths.
Allowed (agent):
obcli config status, obcli rules show, obcli rules metadata, obcli rules explain
obcli --format … status, sql (read-only when no policy; do not attempt write SQL unless the user explicitly asks and policy allows — agent contract is still read-only), schema tables
obcli --version, obcli --help
Human operator: DSN via printf '…' | obcli config set-dsn, policy.json edits. Legacy config.json is ignored for write enablement.
Prerequisites
obcli --version
pip install oceanbase-cli
# or: pip install -e ./oceanbase-cli
DSN: encrypted at rest (human setup; agent does not touch)
Do not put oceanbase://... in environment variables for routine use.
Human stores DSN (stdin); agent does not run:
printf '%s' 'oceanbase://user:pass@host:2881/db' | obcli config set-dsn
On disk the DSN is encrypted in ~/.config/obcli/dsn.enc; key .obcli-key (0600). Do not paste into model context.
Optional: obcli --dsn '...' (visible in ps).
Global options before subcommand
obcli --format json sql "SELECT 1"
obcli --format json status
Commands (agent-safe subset)
| Goal |
Command |
Agent may run? |
| Paths / flags |
obcli config status |
Yes |
| Policy |
obcli rules show, metadata, explain |
Yes |
| Read-only SQL |
obcli sql, status, schema tables |
Yes |
| Store/clear DSN |
config set-dsn, clear-dsn |
No (human) |
Write SQL (agent: not supported)
sql_writes_supported: false (agent contract); policy_governs_writes when local policy.json is enforced — then humans may run writes if block_rules allow.
sql_writes_opt_in_flag: null — there is no CLI flag to opt into writes without policy.json.
- Without a non-empty parsed
policy.json, write-class SQL → OBCLI-NO-WRITE.
Optional local policy (policy.json)
~/.config/obcli/policy.json — human-maintained; agent must not edit. block_rules deny by regex; when enforced, they are the primary gate for write SQL (deny wins; no match → execute).
Environment (non-secret)
| Variable |
Role |
XDG_CONFIG_HOME |
Config root |
OBCLI_AUDIT_LOG |
Audit JSONL path (human) |
Do not use env for OCEANBASE_DSN / MYSQL_DSN for routine DSN.
Further reading
1---2name: oceanbase-cli3description: >-4 Runs OceanBase (MySQL protocol) via `obcli` shell only; sql_writes_supported false for agents; without non-empty policy.json, OBCLI-NO-WRITE on DML/DDL; with policy.json, block_rules govern writes.5 Agent must not modify obcli config or run config set-dsn/clear-dsn. Encrypted local DSN under ~/.config/obcli; optional policy.json;6 pymysql-backed `sql`, `status`, `schema tables`.7license: MIT8metadata:9 source: https://skillmd.com/skills/oceanbase/oceanbase-cli10---1112# oceanbase-cli (`obcli`) — Agent invocation1314**Invoke via shell** (`obcli ...`). **`obcli sql`:** read-style statements by default; **DML/DDL** need a **present, non-empty** **`policy.json`** (parsed object), then **`block_rules`** decide allow/deny (**`policy_governs_writes`** in **`obcli rules show`** / **`metadata`**). No **`config.json`** write toggle, no opt-in flag, no env to skip policy.1516## Agent: must not modify obcli configuration1718The agent **must not modify** any obcli configuration on disk, and **must not** run commands that change it.1920**Forbidden (agent):**2122- Using **any file/read/write tool** on **`~/.config/obcli/`** or **`$XDG_CONFIG_HOME/obcli/`** (including reading `config.json` to “fix” settings). Use **`obcli config status`** / **`obcli rules show`** for safe summaries.23- Editing, creating, or deleting files there, including **`config.json`**, **`policy.json`**, **`dsn.enc`**, **`.obcli-key`**, **`audit.jsonl`**.24- Running **`obcli config set-dsn`**, **`obcli config clear-dsn`**, or shell redirection that writes to those paths.2526**Allowed (agent):**2728- **`obcli config status`**, **`obcli rules show`**, **`obcli rules metadata`**, **`obcli rules explain`**29- **`obcli --format … status`**, **`sql`** (read-only when no policy; **do not** attempt write SQL unless the user explicitly asks and policy allows — agent contract is still read-only), **`schema tables`**30- **`obcli --version`**, **`obcli --help`**3132**Human operator:** DSN via **`printf '…' | obcli config set-dsn`**, **`policy.json`** edits. Legacy **`config.json`** is ignored for write enablement.3334## Prerequisites3536```bash37obcli --version38```3940```bash41pip install oceanbase-cli42# or: pip install -e ./oceanbase-cli43```4445## DSN: encrypted at rest (human setup; agent does not touch)4647- **Do not** put `oceanbase://...` in environment variables for routine use.48- Human stores DSN (stdin); agent **does not** run:4950 ```bash51 printf '%s' 'oceanbase://user:pass@host:2881/db' | obcli config set-dsn52 ```5354- On disk the DSN is **encrypted** in **`~/.config/obcli/dsn.enc`**; key **`.obcli-key`** (0600). **Do not** paste into model context.55- Optional: **`obcli --dsn '...'`** (visible in `ps`).5657## Global options before subcommand5859```bash60obcli --format json sql "SELECT 1"61obcli --format json status62```6364## Commands (agent-safe subset)6566| Goal | Command | Agent may run? |67|------|---------|----------------|68| Paths / flags | `obcli config status` | Yes |69| Policy | `obcli rules show`, `metadata`, `explain` | Yes |70| Read-only SQL | `obcli sql`, `status`, `schema tables` | Yes |71| Store/clear DSN | `config set-dsn`, `clear-dsn` | **No** (human) |7273## Write SQL (agent: not supported)7475- **`sql_writes_supported`:** **`false`** (agent contract); **`policy_governs_writes`** when local **`policy.json`** is enforced — then humans may run writes if **`block_rules`** allow.76- **`sql_writes_opt_in_flag`:** **`null`** — there is no CLI flag to opt into writes without **`policy.json`**.77- Without a non-empty parsed **`policy.json`**, write-class SQL → **`OBCLI-NO-WRITE`**.7879## Optional local policy (`policy.json`)8081**`~/.config/obcli/policy.json`** — human-maintained; agent **must not** edit. **`block_rules`** deny by regex; when enforced, they are the **primary** gate for write SQL (deny wins; no match → execute).8283## Environment (non-secret)8485| Variable | Role |86|----------|------|87| `XDG_CONFIG_HOME` | Config root |88| `OBCLI_AUDIT_LOG` | Audit JSONL path (human) |8990Do **not** use env for **`OCEANBASE_DSN`** / **`MYSQL_DSN`** for routine DSN.9192## Further reading9394- [oceanbase-cli/README.md](../../oceanbase-cli/README.md)