Skip to content

CLI AI Agents

radix29 edited this page Oct 31, 2026 · 1 revision

← goSSMS Home · ← CLI

CLI — AI agents

goSSMS' command line was designed to be driven by an AI agent as much as by a script: a stable JSON envelope, exit codes that name the failure, hints that name the next step, a default of read-only, and three commands that describe gossms to a machine — all of them generated from the live command tree, so they cannot go stale against the binary that prints them.

Command Prints Outside the envelope?
agent guide The manual an agent reads before its first call Yes — markdown by default, -o text plain lines, -o json sections
agent schema The whole command catalog as JSON Yes — JSON whatever -o says (text/json; others refused)
agent context What a profile actually reaches on this server No — a normal envelope

agent guide

gossms agent guide                 # the full manual (markdown)
gossms agent guide --brief         # the system-prompt edition (< 6,000 bytes, ~1,500 tokens)
gossms agent guide --topic rules   # one section: overview | rules | calling | output | exit-codes | commands | recipes
gossms agent guide --topic db      # one command group: every command's usage, options, examples
gossms agent guide --topic object -o json
gossms agent guide -p dev          # connects and adds "Your environment" (agent context's answer)

Sections, in fixed order:

Id
overview What gossms is
rules Rules the agent must follow (below)
calling How to call it
output The output contract
exit-codes Generated from the exit-code table
commands The command index: command, operation class, summary (--brief: one row per group)
recipes Explore a schema, read data, check space, review settings, tune a slow query, script and export, make a safe data fix, diagnose a slow server

The first lines are the title and gossms <version> · CLI schema <n>, so a cached guide can be told stale. Only rules and recipes are hand-written prose; every gossms … in them is tested to parse, so a recipe can name only commands the build actually has.

Given a profile or --server (on the command line or via GOSSMS_PROFILE), the guide connects and appends an environment section — agent context's answer for the same connection, tables included (in --brief, each table's first 15 rows plus a count of the rest). When the context fails, the guide still prints but the exit code is the error's, and the section names the failure: an agent never mistakes a guide without its environment for one with it.

jsonl, csv and tsv are refused — the guide is a document, not a table.

The rules (as the guide states them)

  1. Pass -p <profile> to every command that connects. Never put a password on the command line: a profile carries its own.
  2. The default is read-only. query run and plan actual refuse a script above --allow (default read; write, ddl, admin) with exit 7 before connecting, and the profile's ceiling caps --allow. Raise it only with the user's explicit approval of that change.
  3. Before a change: --dry-run (classify only), then --transaction rollback (run and undo), then the real run, with --max-rows-affected <n> when the count is known.
  4. Send T-SQL through stdin (--file -) or --sql-base64, not --sql: no shell quoting can damage them.
  5. Output is capped: 200 rows per set, 256 characters per cell. Check truncated; use --max-rows 0 or --out-file <path> for everything.
  6. Never run gossms without a command: that starts the interactive UI.
  7. Read the exit code first. On an error, hint names the next step; follow it rather than guessing a spelling.

agent schema

The machine-readable catalog an agent builds tool definitions from — every command, argument, option and example, generated from the tree:

gossms agent schema                    # everything
gossms agent schema object             # one group
gossms agent schema query run          # one command

The document (JSON, exit 0, not the envelope):

Key
schemaVersion The envelope's version — bump your parser on this, not on the build
gossmsVersion The build's version, so a cached catalog can be told stale
formats The --output values
exitCodes[] exit, code, meaning — the whole table
globals[] The global options
groups[] name, summary of each group
commands[] path ("object list"), summary, description, operationClass (read/write/ddl/admin), arguments[] (name, help, format, required, repeat), options[], examples[]

An option is name, short, type (bool|string|int|enum|list|repeat), enum, default typed by type, negation (a bool's --no-<name>), env and help. Every key is always present, so a tool-builder can iterate without special cases; hidden commands are left out. gossms help -o json prints the same document for the same topic.

agent context

What an agent should know before it acts through a profile:

gossms agent context -p dev
gossms agent context -p dev -o json

A record — serverName, productVersion, majorVersion, edition, login, isSysadmin, database, databaseRoles (the fixed roles held there), defaultAllow (read), maxAllow (the ceiling --allow cannot pass; admin ad hoc), maxAllowSource (profile / default / ad hoc) — plus two named sets:

  • databases: name, state, accessible (HAS_DBACCESS: false for a database not ONLINE, whoever asks; NULL when the server does not say), is_system.
  • missing_permissions: permission, scope, commands, effect — each permission a gossms command needs that the login is known to lack, what it breaks and how: a read that fails with exit 9, or columns that read NULL with a warning. An alternative grant counts (2022's VIEW SERVER PERFORMANCE STATE stands for VIEW SERVER STATE); a permission the server does not answer for is left out rather than guessed.
  • profiles: the profiles saved on this machine — name, server, database, max_allow.

A probe that fails is a warning, not an error: context is answered on a leg, not refused.

missing_permissions right-sizes the agent's plan: a profile whose login lacks VIEW SERVER STATE will exit 9 on every monitor command, so the agent picks monitor querystore (needs VIEW DATABASE STATE) or declines and says why — before burning turns discovering it.

Driving gossms from an agent

A minimal system-prompt assembly:

{ echo "You manage SQL Server with the gossms CLI. Follow its rules.";
  gossms agent guide --brief; } > system-prompt.md

A tool definition straight from the schema (the pattern, for any command):

gossms agent schema query run -o json | jq '.commands[0] | {
  name: .path, description: (.description // .summary),
  class: .operationClass, examples }'

The discipline that keeps a session safe (all of it enforced by gossms itself, not by convention):

Situation Call
First call on a profile gossms agent context -p dev -o json — know the ceiling and the gaps
Any read gossms <group> <command> -p dev -o json — reads need nothing special
T-SQL longer than one line gossms query run -p dev --file - <<'SQL' … SQL or --sql-base64
Before any change gossms query classify --file fix.sql --allow write — exit 7 unless the script really is write
Rehearse a change gossms query run -p dev --file fix.sql --allow write --transaction rollback — runs, reports rowsAffected, keeps nothing
Make a change, sized gossms query run -p dev --file fix.sql --allow write --max-rows-affected 10 — commits only ≤ 10 rows, else rolls back, exit 7
A gosmo write (config, drop, kill…) <command> … --allow admin --dry-run first; show the printed tsql; then the real run
Exit 7 anywhere Read detectedClass/allowedClass/statements; do not silently raise --allow — that is the user's decision

Integration notes

  • Versioning: cache the guide/schema keyed on gossmsVersion + schemaVersion; both are printed by version, the guide's header and the schema.
  • The envelope's schemaVersion changes only on a breaking structure change, so JSON parsers can pin on it.
  • Nothing is hand-written in the machine outputs: --help, agent schema, the commands topic and the exit-code topic all come from the tree and the exit-code table; tests fail the build if a command is missing from the schema or a recipe names a command that does not parse.
  • The audit log records every above-read call and every refusal the agent makes, so a human can review exactly what was run — see Safety and audit.

Where to go next

Want Page
The rules enforced by which mechanism Safety and audit
The envelope the agent parses Output and exit codes
The recipes in full gossms agent guide --topic recipes

Clone this wiki locally