sscli

SQL Server CLI for AI coding agents.

One install. Your agents automatically know how to inspect SQL Server databases, run safe queries, and export results.

Why sscli?

Why not sqlcmd

sqlcmd is a great general-purpose SQL Server client, especially for interactive sessions and ad-hoc work.

For tool-calling agents, sqlcmd tends to be a poor fit because it's optimized for humans, not for structured, repeatable automation:

• Output is hard to consume: sqlcmd output is human-oriented text; agents usually want stable markdown tables or a single JSON object they can reliably parse.
• Schema discovery is manual: you end up writing catalog queries (sys.tables, INFORMATION_SCHEMA, etc.) instead of calling purpose-built primitives like sscli tables, sscli describe, and sscli columns.
• No safety guardrails: sqlcmd will happily run destructive statements if an agent makes a mistake. sscli sql blocks writes by default and requires --allow-write for mutations.
• More setup friction: sqlcmd is typically installed via Microsoft tooling and may require ODBC drivers depending on platform/CI image; sscli is a single binary with config + env var discovery built in.
• No agent integration: sscli can install a reusable skill/extension so agents "know the tool" without you pasting usage docs into every prompt.

Keep sqlcmd for interactive SQL. Reach for sscli when you want safe-by-default queries, fast schema inspection, and output formats that are easy for agents to use.

Quick Start (Agent Users)

1. Install sscli

# macOS/Linux
brew install jwcraig/tap/sscli

# Windows (PowerShell)
scoop bucket add jwcraig https://github.com/jwcraig/scoop-bucket
scoop install sscli

# or with cargo (any platform)
cargo install sscli

2. Teach your agents

sscli integrations skills add --global   # Claude Code + Codex
sscli integrations gemini add --global   # Gemini CLI

Done. Your agents now know how to browse schemas, run safe queries, and export results.

What changes?

Manual Usage

For humans who want to use sscli directly.

1-minute setup (first run)

# Create a starter config in ./.sql-server/config.yaml (safe defaults)
sscli init

# Set the password env var referenced by passwordEnv in your config. sscli also reads
export SQL_PASSWORD='...'

# Sanity-check connectivity + server metadata
sscli status

# See the effective settings + which config file was used
sscli config

Common commands

sscli status                              # Check connectivity
sscli tables                              # List tables
sscli tables --like "%User%" --describe   # Describe all User-related tables
sscli describe Users                      # DDL, columns, indexes, triggers
sscli describe T_Users_Trig               # Trigger definition (auto-detected)
sscli sql "SELECT TOP 5 * FROM Users"
sscli sql --file [path/to/file]           # Run long queries, execute bulk statements
sscli update                              # Check for new releases (alias: sscli upgrade)

Installation

Homebrew (macOS/Linux)

brew install jwcraig/tap/sscli

Scoop (Windows)

scoop bucket add jwcraig https://github.com/jwcraig/scoop-bucket
scoop install sscli

Quick install script

curl -sSL https://raw.githubusercontent.com/jwcraig/sql-server-cli/main/install.sh | sh

Cargo binstall (fast, no compilation)

cargo binstall sscli

From source

cargo install sscli

Prebuilt binaries

Download from GitHub Releases.

Development build

git clone https://github.com/jwcraig/sql-server-cli sscli
cd sscli
cargo build --release
./target/release/sscli --help

Updating

# Check if you're up to date (alias: `sscli upgrade`)
sscli update

# Homebrew
brew upgrade sscli

# Cargo
cargo install sscli --force

Automatic update notifications (optional)

By default, sscli does not check for updates automatically.

To enable lightweight update notifications (stderr, TTY-only, cached), create:

• ~/.config/sscli/settings.json (Linux/XDG default)
• macOS often uses ~/Library/Application Support/sscli/settings.json by default

Example settings.json:

{ "autoUpdate": true }

Agent Integration

Supported agents

Per-project vs global

What the skill teaches agents

The installed skill file tells agents:

• When to use sscli (database inspection, schema discovery, safe queries)
• Available commands and their purpose
• Output preferences (markdown for context efficiency, --json for structured data)
• Safety model (read-only default, --allow-write for mutations)

Configuration

sscli supports three ways to configure a connection (highest priority wins):

# 1) CLI flags (one-off / scripts)
sscli status --server localhost --database master --user sa --password '...' # alias: --host

# 2) Environment variables (CI-friendly)
export SQL_SERVER=localhost SQL_DATABASE=master SQL_USER=sa SQL_PASSWORD='...'
sscli status

# 3) Config file (recommended for repeated use)
sscli init && export SQL_PASSWORD='...' && sscli status

Creating a config file

Generate a commented template (writes ./.sql-server/config.yaml by default):

sscli init

Or copy the example file in this repo:

mkdir -p .sql-server
cp config.example.yaml .sql-server/config.yaml

Config discovery (where sscli looks)

1. --config <PATH>
2. SQL_SERVER_CONFIG / SQLSERVER_CONFIG
3. Walk up from CWD looking for .sql-server/config.{yaml,yml,json} or .sqlserver/config.{yaml,yml,json}
4. Global config: $XDG_CONFIG_HOME/sql-server/config.{yaml,yml,json} (platform-dependent)
5. Environment variables
6. Hardcoded defaults

Run sscli config to confirm which config file is being used and what values are in effect.

Example config.yaml

defaultProfile: default
profiles:
  default:
    server: localhost
    port: 1433
    database: master
    user: sa
    passwordEnv: SQL_PASSWORD
    encrypt: true
    trustCert: true

For a fully commented example (including settings.output.*, timeout, and defaultSchemas), see config.example.yaml.

Environment variables

Environment variables override values from the config file.

.env file support: sscli automatically loads a .env file from the current directory if present, reading any of the supported variables listed below. Use --env-file to load a different file (e.g., --env-file .env.dev). This is useful for local development without polluting your shell environment.

sqlcmd compatibility: The following sqlcmd environment variables are also supported:

Commands

Core (shown in --help):

Advanced (shown in help --all):

Note: sscli sessions filters by client host name using --client-host. --host is reserved as an alias for --server.

Output Formats

JSON output emits exactly one object to stdout. Errors go to stderr.

Safety

sscli sql enforces read-only mode by default:

• Allowed: SELECT, WITH (CTEs), whitelisted stored procedures
• Blocked: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, MERGE, etc.

Override with --allow-write when you intentionally need mutations.

JSON Contract (v1)

Each command returns a stable top-level object:

Errors (stderr):

{ "error": { "message": "...", "kind": "Config|Connection|Query|Internal" } }

Testing

cargo test

DB-backed integration tests (opt-in):

SSCLI_INTEGRATION_TESTS=1 SQL_SERVER_CONFIG=/path/to/config.yaml \
SQL_PASSWORD=... cargo test