sqlcl-cli

oasis-sqlcl — an AXI-compliant CLI for Oracle SQLcl on the Oasis databases. Manage saved connections (list/add/remove/switch) and run SQL — with token-efficient TOON output built for autonomous agents.

Extracted from the oasis-core Claude Code plugin so it can be installed, versioned, and released on its own.

Prerequisites

This CLI drives Oracle SQLcl (the sql binary), which must be installed separately. It is resolved from, in order: $SQLCL_PATH, ~/.oasis/sqlcl/bin/sql, common install locations, then PATH. Download SQLcl from oracle.com/sqlcl and unpack it into ~/.oasis/sqlcl/ (or anywhere on PATH).

Quick Start

Install the sqlcl-cli skill in the Agent Skills format with npx skills:

npx skills add oasissys/sqlcl-cli --skill sqlcl-cli -g

That is the entire setup — the skill teaches your agent the CLI, and it runs without a global install as npx -y @oasissys/sqlcl-cli (Node 20+ required). Installing the skill itself needs GitHub access to this private repo.

-g installs the skill for all projects (~/.claude/skills/); drop it to install for the current project only.

Other ways to install

Zero setup

Any capable agent can run the CLI directly with nothing installed. Just tell your agent:

Execute `npx -y @oasissys/sqlcl-cli` to get Oasis SQLcl (Oracle DB) tools.

Global install + session hook

Want the CLI on PATH and the active Oracle connection fed into every agent session?

npm install -g @oasissys/sqlcl-cli   # installs `oasis-sqlcl` (and the `sqlcl-cli` alias)
oasis-sqlcl setup

setup registers a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces the active Oracle connection at session start — restart your agent session after running it. If you use the oasis-core Claude Code plugin, it already ships this hook; skip setup or remove one of the two.

From a clone (development)

pnpm install && pnpm run build && pnpm link --global

Connections

Named connections live in SQLcl's own wallet (~/.dbtools/connections/, %APPDATA%\dbtools\connections\ on Windows) — the same store Oracle's SQLcl MCP reads, so every surface stays in sync. The only state kept in ~/.oasis.json (shared with the other oasis CLIs) is which connection is active.

oasis-sqlcl add oasisdev --host db.internal --service ORCLPDB1 --user app --password secret
oasis-sqlcl connections          # list saved connections + the active one
oasis-sqlcl use oasisdev         # switch the active connection
oasis-sqlcl rm oasisdev          # remove a connection

add and test connect to verify before saving — a failure surfaces the actual ORA-… error.

Use

oasis-sqlcl                                                    # live view: connections + active
oasis-sqlcl run "SELECT id, name FROM patients WHERE rownum <= 10"
oasis-sqlcl run "SELECT * FROM dual" --conn oasisqa            # target a specific connection
oasis-sqlcl run "UPDATE t SET x = 1 WHERE id = 5" --raw        # raw SQLcl output for DML/PL-SQL

Every command supports --help. Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 (success/error/usage).

Development

pnpm run dev -- run "SELECT 1 FROM dual"   # run from source
pnpm test                                   # vitest
pnpm run lint                               # eslint
pnpm run build:skill                        # regenerate SKILL.md

Releases are cut by release-please from conventional commits on main. Do not hand-edit CHANGELOG.md, .release-please-manifest.json, or skills/sqlcl-cli/SKILL.md — they are generated.