Repository navigation
CLI Getting Started
How gossms decides it is being called from a script, how its arguments are
parsed, how a saved connection (a profile) is used, and where a password
may and may not appear.
- Output and exit codes — what the answer looks like
- AI agents — the machine-readable manual
- Safety and audit — why writes refuse by default
| Invocation | Behaviour |
|---|---|
gossms (no argument at all) |
Starts the interactive TUI — but only with both stdin and stdout on a terminal. Otherwise it exits 1 at once, with one stderr line pointing at gossms agent guide
|
gossms --version / -version / -v
|
The version block, byte-identical to every earlier release (the Homebrew install test matches it). 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 |
No argument means the UI, any argument means the command line; the version
flags are the one exception, kept for compatibility. Without the terminal
check, a bare gossms with piped stdio would open /dev/tty and wait for keys
no one sends — the check refuses that instead. On Windows the check is
console-mode based: under mintty without ConPTY the stdio are pipes and the UI
is refused, which is also the case where keys could not have been read anyway.
$ gossms --version
gossms v0.2.0
Commit: 72a0e3c
Built: 2026-11-01T09:00:00Z
Platform: linux/amd64
License: GPL-3.0-or-later
gosmo: v0.1.1gossms <command> [arguments] [options]
gossms <group> <command> [arguments] [options]
gossms <group> <sub-group> <command> [arguments] [options]
gossms help [<group>] [<command>...]
gossms <command> --help
- The command is the deepest path the positional words spell. Global options
may precede it:
gossms -o json version. - A group alone (
gossms db) is a usage error whose hint lists its commands. Options with no command (gossms -p dev) too.
-
--name valueand--name=valueare the same; a short alias is-x valueor-x=value. - A bool is
--name, or--no-namefor false; it takes no value —--quiet=yesis an error. - A list option may repeat and/or take comma-separated items
(
--type table,view); one with a fixed vocabulary (object list --type) refuses an item outside it. - A non-list option given twice is an error — there is no "last one wins".
-
-is a value or a positional argument (stdin where a file is expected), never an option. A value may start with-but not--; spell such a value--name=--value(that is howserver config settakes a negative value). -
--ends the options: every later token is positional. - An option absent from the command line takes its environment variable (where one is defined), else its default.
| Variable | Sets |
|---|---|
GOSSMS_PROFILE |
--profile |
GOSSMS_SERVER |
--server |
GOSSMS_DATABASE |
--database |
GOSSMS_AUTH |
--auth |
GOSSMS_USER |
--user |
GOSSMS_TENANT_ID |
--tenant-id |
GOSSMS_CLIENT_ID |
--client-id |
GOSSMS_ENCRYPT |
--encrypt |
So a CI job can export GOSSMS_PROFILE once and let every command carry on:
export GOSSMS_PROFILE=build-agent
gossms agent context # no -p anywhere
gossms query run --file smoke.sql -o json@path (relative to the working directory) is replaced by the file's lines,
which avoids shell quoting entirely:
# release-check.args
query run
-p prod-ro
--file
checks/smoke.sql
-o json
gossms @release-check.args- A line starting with
-is one option: split at its first whitespace into option and value, unless written--name=value. - Any other line is one token — command words go on separate lines, a value with spaces needs no quoting.
- Blank lines are skipped; a BOM and CRLF line ends are tolerated.
- No recursion:
@xinside a response file is a literal token. So is@xafter--, and@xas the value of an option that takes one.
Everything the parser refuses is USAGE_ERROR, exit 2: unknown command or
option, missing or extra arguments, a missing value, a value the type rejects
(not an integer, not in the enum), a repeated option, an unreadable response
file. Unknown options are never ignored. Where a command or option name is
close (edit distance ≤ 2), the hint is a did-you-mean:
$ gossms versionn
STATUS: ERROR
COMMAND:
DURATION_MS: 0
ERROR_CODE: USAGE_ERROR
MESSAGE: unknown command "versionn"
HINT: Did you mean `gossms version`?
gossms: USAGE_ERROR: unknown command "versionn"
$ echo $?
2
Even though parsing failed, a usage error is rendered in the format the raw
command line asked for — gossms -o json versionn answers parseable JSON.
gossms --help, gossms help, gossms help <group> [<command>...] (a
sub-group's command is gossms help server config get) and
<command> --help print plain text for people, outside the envelope, exit
0. All of it is generated from the command tree: usage line, description,
arguments, options, global options, examples.
gossms help # the groups and the global options
gossms help monitor # the monitor commands, one line each
gossms help monitor deadlocks # usage, every option with its default and env var, examplesHelp with --output json is the command schema of the same topic — exactly
what gossms agent schema prints — and help in any other format is refused.
The first line of the top-level help is the pointer for AI agents:
AI agents: run gossms agent guide for complete usage instructions. Every
gossms … named in a hint, help text or example is tested to parse, so a
pointer can never name a command that does not exist.
A profile is a saved connection the user has named in the TUI: the Connect dialog's Profile… button, on the History row selected, sets
-
Profile Name — letters, digits,
-,_,., starting with a letter or digit, at most 64 characters, unique ignoring case. Clearing it makes the entry a plain recent connection again. -
Allowed Operations — the ceiling (
max_allow):read,write,ddloradmin(the default). The safety model enforces it: no--allowraises a profile above its ceiling.
Both are stored on the connection in config.json, outside the data a saved
password is sealed to, so naming a connection never invalidates its password.
A named connection is exempt from the 30-entry recent-connections trim.
The command line only reads the configuration: it never writes
config.json, never creates gossms.key, never sweeps temp files, never
re-seals a password, never opens gossms.log. A running TUI writes
config.json atomically, so a command sees the old file or the new one — the
TUI and the CLI can be open at the same moment. Without the key file every
saved password stays sealed (password: unreadable). A config.json that
exists but cannot be read is GENERAL_ERROR, not an empty list.
$ gossms profile listLists the named profiles, sorted by name: name, kind (profile, or
recent with --all), server, port, database, auth, user,
max_allow, password (saved / none / unreadable — a password is never
shown). --all adds the unnamed recent connections, most recent first, under
their generated name server,port,database,user — which --profile also
accepts, so a connection can be used before it is named.
gossms profile list --all -o jsongossms profile show dev
gossms profile show dev -o jsonOne profile's full settings as a record: server, port, database, auth, user,
tenant and client ids, TLS options, extraProperties (keys only — a value may
be a secret), maxAllow, and whether the saved password opens. A password
that cannot be opened adds a warning, not an error.
gossms profile test dev
gossms profile test dev --database master -o jsonConnects the way every command will — the profile with any connection option
given here laid over it — and answers: serverName, productVersion,
productLevel, edition, platform, login, connectedDatabase, auth,
passwordSource (profile, env:<VAR>, stdin, none), maxAllow and
latencyMs (the whole connect). The header's SERVER/DATABASE name the
target also on failure, and the exit code says what failed:
AUTH_FAILED (4), CONNECTION_FAILED (3), TIMEOUT (6), NOT_FOUND (8).
profile test takes its profile positionally; every other command takes
--profile/-p.
A command that connects — agent context, agent guide given a profile, the
db, server and object commands, query run/parse, plan, script,
data, monitor, xevent, security — takes these options on top of the
profile. Precedence: command line > environment variable > profile >
default.
| Option | Alias | Env | |
|---|---|---|---|
--server <host[\instance][,port]> |
-S |
GOSSMS_SERVER |
The Connect dialog's syntax: tcp:host,1433, host\instance
|
--port <n> |
When --server names none; naming two different ports is a usage error |
||
--database <name> |
-d |
GOSSMS_DATABASE |
Initial database |
--auth <method> |
GOSSMS_AUTH |
sql, windows, entra-default, entra-password, entra-msi, entra-sp, entra-azcli; entra-interactive and entra-device-code are refused |
|
--user <name> |
-U |
GOSSMS_USER |
Login (sql, windows, entra-password) |
--tenant-id <id> |
GOSSMS_TENANT_ID |
Entra tenant | |
--client-id <id> |
GOSSMS_CLIENT_ID |
Entra client: service principal, user-assigned managed identity | |
--password-env <VAR> |
Name of the variable holding the password or client secret | ||
--password-stdin |
First line of stdin is the password or client secret | ||
--encrypt <optional|mandatory|strict> |
GOSSMS_ENCRYPT |
Connection encryption | |
--trust-server-certificate |
Skip certificate validation (development only) | ||
--host-name-in-certificate <name> |
Name the certificate must carry | ||
--application-intent <readwrite|readonly> |
readonly routes a listener to a readable secondary |
||
--connect-timeout <sec> |
1 to 30, default 15 |
They are options of the commands that connect, not globals:
gossms version --server x is an unknown option. Without a profile the call
is ad hoc: --server is required, and the ceiling is whatever --allow
asks for (admin available).
-
No password on the command line, ever — it would reach process lists,
shell history and agent logs. A profile's saved password (Remember Password)
is used as the TUI uses it; otherwise
--password-envor--password-stdin, not both. SQL Authentication with no password anywhere is refused before dialling (AUTH_FAILED, a hint naming both options). -
A saved password goes only where it was saved for. An override of the
server (ignoring case), port, user, authentication method, Entra tenant or
client — from an option or its environment — or one that weakens TLS
(
--encryptlower than saved,--trust-server-certificateturned on, another--host-name-in-certificate) leaves the saved password out; pass--password-envor--password-stdinthen. The database, a stronger--encrypt,--no-trust-server-certificateand--application-intentkeep it.
# ad hoc, password from the vault through a variable — never an argument
GOSSMS_PW=$(vault kv get -field=pw secret/dev) gossms db list \
-S devsrv,1500 -d Sales --auth sql -U app_user --password-env GOSSMS_PW
# password through stdin (not with --file -: both want stdin)
printf '%s\n' "$PW" | gossms server info -S prod -U svc --auth sql --password-stdin- A field the method does not read is not sent, as in the Connect dialog
(
--tenant-idwithentra-msiis dropped). -
Entra MFA and Device Code are refused (
AUTH_FAILED): they prompt a person, and the token cache lives one process, so every call would prompt again. Useentra-default,entra-azcli,entra-msiorentra-sp. - The session's
program_nameon the server isgoSSMS - CLI— filtermonitor sessions --programby it, and the CLI's own events are excluded fromxevent capture.
A failed connect maps to an exit code by error type and number, never by message text:
| What happened | Code |
|---|---|
| The server refuses the login (Msg 18456 and relatives), or Entra refuses the credential |
AUTH_FAILED (4) |
| A database the login cannot open (Msg 4060, or 4063 with the fallback) |
NOT_FOUND (8) |
The attempt outlives --connect-timeout, or a network timeout |
TIMEOUT (6) |
| Anything else — unreachable, TLS |
CONNECTION_FAILED (3) |
| Want | Page |
|---|---|
| What the answer looks like, formats, limits, exit codes | Output and exit codes |
Teaching an agent, agent guide/schema/context
|
AI agents |
Why UPDATE exits 7 by default, and the write flags |
Safety and audit |
| The commands by area | Databases · Server · Objects and scripting · Query and plans · Data · Monitoring · Security |
- Getting connected
- Browsing and editing
- Diagnosing and tuning
- Server features