Skip to content

Command Line

radix29 edited this page Oct 31, 2026 · 2 revisions

← goSSMS Home

Command Line

goSSMS is also a command line. gossms with any argument runs a command instead of the UI: it parses the arguments, does one thing, writes one parseable answer to stdout, and exits with a code that says how it went. No raw mode, no screen, no TUI log file — the same catalog reads, plans, monitoring and writes the TUI does, for shell scripts, cron jobs, CI pipelines and AI agents.

The full contract lives in the repository at docs/cli.md; this wiki expands it topic by topic below. The binary carries the same manual: gossms agent guide is generated from the live command tree, so it always describes the version you are running.

(The command line landed after v0.1.1 and ships with the next release.)

CLI documentation

Page
Getting started Modes, argument syntax, response files, help, environment variables, profiles, connecting, and where passwords may and may not go
Output and exit codes The envelope, the six formats (text json jsonl csv tsv markdown), output limits, --out-file, every exit code, and how to read the answer in a script
AI agents agent guide, agent schema and agent context: teaching an agent to drive gossms, and checking what a profile can reach
Databases db list/info/files/space/log-usage/table-sizes/set/create/drop/scoped-config — inventory, space, options, and database lifecycle
Server server info/memory/volumes/log/config/traceflag — instance facts, memory, error log, sp_configure and trace flags
Objects and scripting object list/search/describe/definition/dependencies/indexes/stats and script object/db
Query and plans query run/parse/classify, parameters, transaction wrapping, and plan estimated/actual/cached
Data data top/sample/count/profile/export/import — reading, profiling and bulk-moving rows
Monitoring monitor sessions/blocking/waits/top-queries/querystore/deadlocks/kill and xevent sessions/capture
Security security logins/users/roles/role-members/permissions
Safety and audit The operation classes, --allow and the profile ceiling, the write layer, --dry-run/--confirm, and the audit log

The two modes

Invocation Behaviour
gossms (no argument at all) Starts the interactive TUI — but only with both stdin and stdout on a terminal. Piped or redirected, it exits 1 at once with a line pointing at gossms agent guide
gossms --version / -v The version block, byte-identical to every earlier release; extra arguments are ignored
gossms <anything else> The command line. The TUI is never started, its log file is never opened, the terminal is never put in raw mode

The rule: no argument means the UI, any argument means the command line.

A two-minute tour

gossms version                      # the CLI answers at all? (exit 2 until it ships)
gossms help                         # the command groups, their commands, one line each
gossms help db                       # one group's commands
gossms help query run                # one command: usage, every option, examples
gossms agent guide                   # the whole manual, generated from the live tree
gossms profile list                  # the saved profiles (named in the TUI's Connect dialog)
gossms profile test dev              # connect through it: server, edition, login, latency
gossms agent context -p dev          # what that profile can reach, and what it lacks
gossms db list -p dev                # first real read
gossms db -p dev                     # usage error: a group alone is not a command

Everything a command can do, it can do machine-readably: append -o json to any command, -o jsonl to stream rows, or ask gossms agent schema <group> <command> for the command's full definition as JSON.

Syntax in one paragraph

gossms <group> [<sub-group>] <command> [arguments] [options]. Options are --name value, --name=value, or --name / --no-name for bools; lists repeat or take commas; a non-list option given twice is an error; -- ends the options; - means stdin where a file is expected; an absent option takes its environment variable, else its default; @args.txt pulls arguments from a response file. Unknown options are never ignored, and near names get a did-you-mean. Every refusal is USAGE_ERROR, exit 2. Full details: Getting started.

Global options

Option
-o, --output <text|json|jsonl|csv|tsv|markdown> Output format (default text)
-q, --quiet Text and markdown: leave out the header block
--verbose Diagnostic logging to stderr (-v is taken by --version)
--max-rows <n> Rows kept per result set on stdout (default 200; 0 keeps all)
--max-col-width <n> Characters kept per cell (default 256; 0 keeps all)
--max-output-bytes <n> Cap on stdout (default 1048576; 0 is no cap)
--null-text <text> How text and markdown show NULL (default NULL)
--no-headers / --no-messages Leave out column headers / PRINT messages
--out-file <path> Write every row, uncapped, to a file; stdout gets the summary
--force Replace an existing --out-file, --plan-file, --script-file or .xdl file

Limits drop rows from the output, never from the run: a script runs in full whatever --max-rows keeps on stdout. Details: Output and exit codes.

Exit codes

Code Name Meaning
0 OK Success (output may still be truncated — check truncated)
1 GENERAL_ERROR Unexpected or internal error
2 USAGE_ERROR Invalid or unknown arguments
3 CONNECTION_FAILED Server unreachable, TLS or network error
4 AUTH_FAILED Login failed or credentials are missing
5 SQL_ERROR The server returned an error (severity 11+)
6 TIMEOUT Command or connect timeout
7 BLOCKED Refused by the safety model or a missing --confirm
8 NOT_FOUND Profile, database or object does not exist
9 PERMISSION_DENIED The login lacks the required permission
10 PARTIAL Some batches succeeded and some failed
11 UNSUPPORTED The server's version or edition does not support it
130 CANCELLED Ctrl+C or SIGINT (a second Ctrl+C kills the process)

Read the exit code first; on an error the HINT: (or hint in JSON) names the next step.

The command groups

66 commands in 12 groups. Every command that connects takes the connection options; pages carry each command's full contract.

Group Commands Page
version, help version block; help for any topic here
agent guide · schema · context AI agents
profile list · show <name> · test <name> Getting started
db list info files space log-usage table-sizes set create drop scoped-config list/get/set Databases
server info memory volumes log config list/get/set/reset traceflag list/on/off Server
object list search describe definition dependencies indexes stats Objects and scripting
script object [--as <verb>] · db Objects and scripting
query run · parse · classify Query and plans
plan estimated · actual · cached <plan_handle> Query and plans
data top sample count profile export import Data
monitor sessions blocking waits top-queries querystore deadlocks kill Monitoring
xevent sessions · capture Monitoring
security logins list users list roles list role-members permissions Security

Code

cmd/gossms/main.go (mode switch), internal/cli (Main, help, the command tree as tree.go), internal/cli/spec (the tree as data), internal/cli/args (the parser), internal/cli/output (envelope, renderers, exit codes), internal/cli/connect (connection options and resolution), internal/cli/safety (the T-SQL classifier), internal/cli/audit (the audit log), internal/cli/cmd (the handlers), internal/cli/agent (agent guide and agent schema, built from the tree). internal/cli never imports the TUI or tcell: the command line runs without a screen.


Next: Getting started → · Output and exit codes → · AI agents →

Clone this wiki locally