Skip to content

CLI Getting Started

radix29 edited this page Oct 31, 2026 · 1 revision

← goSSMS Home · ← CLI

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.

Modes

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.1

Syntax

gossms <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.

Options

  • --name value and --name=value are the same; a short alias is -x value or -x=value.
  • A bool is --name, or --no-name for false; it takes no value — --quiet=yes is 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 how server config set takes 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.

Environment variables

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

Response files

@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: @x inside a response file is a literal token. So is @x after --, and @x as the value of an option that takes one.

Errors

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.

Help

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, examples

Help 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.

Profiles

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, ddl or admin (the default). The safety model enforces it: no --allow raises 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.

profile list

$ gossms profile list

Lists 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 json

profile show

gossms profile show dev
gossms profile show dev -o json

One 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.

profile test

gossms profile test dev
gossms profile test dev --database master -o json

Connects 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.

Connecting

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).

Passwords

  • 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-env or --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 (--encrypt lower than saved, --trust-server-certificate turned on, another --host-name-in-certificate) leaves the saved password out; pass --password-env or --password-stdin then. The database, a stronger --encrypt, --no-trust-server-certificate and --application-intent keep 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-id with entra-msi is 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. Use entra-default, entra-azcli, entra-msi or entra-sp.
  • The session's program_name on the server is goSSMS - CLI — filter monitor sessions --program by it, and the CLI's own events are excluded from xevent capture.

Connection failures

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)

Where to go next

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

Clone this wiki locally