Repository navigation
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.)
| 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 |
| 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.
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 commandEverything 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.
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.
| 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.
| 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.
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 |
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 →
- Getting connected
- Browsing and editing
- Diagnosing and tuning
- Server features