Command line

oxysdb-cli is Oxys DB Studio without a window. It runs the same commands as the desktop application, by id, with JSON parameters, and prints JSON. Use it in shell scripts, in CI jobs, or from any program that can start a process.

It uses the same settings, saved connections, saved tasks and credential store as the desktop application for your user account, so a connection you saved in the app can be used by id here.

The five modes

Find a command

oxysdb-cli commands > commands.json

The application’s menu items, toolbar buttons and dialog actions run these commands. Each entry’s params text says which fields it takes and what it returns. For example, connection.list takes { filter? } and returns your saved connections with their ids.

Run one command

oxysdb-cli run connection.list
oxysdb-cli run connection.list '{"filter": "acme"}'

The result is printed as indented JSON on standard output. On an error, the message goes to standard error and the exit status is 1.

Each run starts a new session, so nothing stays open between two calls: a command that needs an open connection fails in run mode. Use batch for that.

Run a sequence of commands

batch keeps one session for every line, so you can connect, then browse, query or run tasks:

oxysdb-cli batch <<'EOF'
{"id": "connection.list", "params": {"filter": "acme"}}
{"id": "connection.connect", "params": {"ids": ["<connection id>"]}}
{"id": "connection.browse", "params": {"connection": "<connection id>", "path": [{"kind": "database", "name": "acme_store"}]}}
{"id": "collection.summary", "params": {"connection": "<connection id>", "db": "acme_store", "collection": "orders"}}
EOF

Each line of input is {"id": …, "params": …}; each line of output is one of:

Blank lines are ignored. A line that is not a command gets an error reply and the batch goes on. The batch ends at the end of the input, with exit status 0.

Answer a confirmation

Destructive commands (drop, clear, delete, overwrite on import, sync, running a task…) never run on the first call. They reply with confirmationRequired:

• prompt: the question, its first line being the title (for example Drop Collection);
• typed: a name you must type back, or null;
• confirmLabel: the confirming button’s text in the application, or null for OK;
• harmless: true when nothing can be lost by confirming;
• hold: an identifier to send back, or null.

Show the prompt to whoever decides, then send the same command again with "confirm": true in its params, plus "typed": "<name>" when typed is not null (and "hold" when it was given). In this example the first reply asked for the collection name to be typed:

{"id": "collection.drop", "params": {"connection": "<id>", "db": "acme_store", "collection": "orders_old"}}
{"id": "collection.drop", "params": {"connection": "<id>", "db": "acme_store", "collection": "orders_old", "confirm": true, "typed": "orders_old"}}

A wrong typed name asks again. Read-only connections refuse writes whatever the answer.

Run saved tasks from a script

{"id": "task.open", "params": {"search": "orders"}}
{"id": "task.run", "params": {"tasks": ["<task id>"]}}
{"id": "task.run", "params": {"tasks": ["<task id>"], "confirm": true}}

task.run opens the connections the task needs (asking for a missing password through inputRequired), asks the Run Task question, then runs. Add "async": true to get a job back instead of waiting for the result.

Serve MCP without the window

oxysdb-cli mcp --port 27117 --allow-connection "acme_store (staging)"

Prints the server’s status (including the URL, the access token and ready-made client configurations) on standard output, then serves until you stop it. Keep the token secret. See Local MCP server for AI agents.

Replay a bug report

oxysdb-cli replay oxysdb-problem.zip --connection "Test server" --dry-run

Reads journal.json from a report saved with Help › Report a Problem… and prints, as JSON, each command with what it would do (run, or skip and why). Without --dry-run it connects and runs them, and says how each ended. The journal’s tokens become new names: db#1 the scratch database oxys_replay_db_1, coll#1 the collection coll_1, tab#1 the tab the replay itself opened.

Only database commands are replayed (never preferences, saved connections, Team Sharing or tasks); a command whose parameters were redacted (a file path, a URI, a text) is skipped and says so.

Tips

• Pipe commands through a JSON tool to search it: oxysdb-cli commands | jq '.[] | select(.id | startswith("task."))'.
• In scripts, check confirmationRequired explicitly; never add "confirm": true blindly to every call.
• A crash of the CLI is written to global_exception.log in the logs folder, with a backtrace.

Troubleshooting