Repository navigation
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 |
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.
- Pass
-p <profile>to every command that connects. Never put a password on the command line: a profile carries its own. - The default is read-only.
query runandplan actualrefuse a script above--allow(defaultread;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. - 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. - Send T-SQL through stdin (
--file -) or--sql-base64, not--sql: no shell quoting can damage them. - Output is capped: 200 rows per set, 256 characters per cell. Check
truncated; use--max-rows 0or--out-file <path>for everything. - Never run
gossmswithout a command: that starts the interactive UI. - Read the exit code first. On an error,
hintnames the next step; follow it rather than guessing a spelling.
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 commandThe 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.
What an agent should know before it acts through a profile:
gossms agent context -p dev
gossms agent context -p dev -o jsonA 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.
A minimal system-prompt assembly:
{ echo "You manage SQL Server with the gossms CLI. Follow its rules.";
gossms agent guide --brief; } > system-prompt.mdA 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 |
-
Versioning: cache the guide/schema keyed on
gossmsVersion+schemaVersion; both are printed byversion, the guide's header and the schema. -
The envelope's
schemaVersionchanges only on a breaking structure change, so JSON parsers can pin on it. -
Nothing is hand-written in the machine outputs:
--help,agent schema, thecommandstopic 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.
| 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 |
- Getting connected
- Browsing and editing
- Diagnosing and tuning
- Server features