Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Kater CLI

Global options

The options every command takes, and where they go on the command line.

OptionWhat it doesExample
--jsonMachine-readable output.kater scope list --json
--kater-root ROOTThe project folder, which holds kater_project.yml. By default, the first folder from here up that holds one.--kater-root ~/kater-content
--target NAME, -t NAMEThe target of the profile to run on, in place of its default. KATER_TARGET does the same.kater run --select event_summary.sql --target prod
--profile NAMEThe profile in profiles.yml, in place of the one the project names.kater --profile acme debug
--profiles-dir FOLDERThe folder of profiles.yml. KATER_PROFILES_DIR does the same.kater debug --profiles-dir ci
--scope PATHThe modeling or workspace scope for one command.--scope connections/snowflake_prod_connection/workspaces/ad_reporting
--versionShows the installed CLI version.kater --version
--help, -hShows a command’s subcommands, options and usage.kater query --help
--log-format text|json|debugHow the progress lines look. json prints one JSON line for each event. Before the command only.kater --log-format json run
--log-level LEVELThe least level of progress line that prints: debug, info, warn, error or none. Before the command only.kater --log-level debug compile
--quiet, -qPrints only errors while a command works, and its answer. Before the command only.kater -q run
--no-colorPrints no colour. NO_COLOR does the same. Before the command only.kater --no-color test
--log-path PATHThe folder of the log file, in place of logs/ at the content root. Before the command only.kater --log-path /tmp/kater compile
--warn-errorTurns warnings into errors: a command that warns exits 1. Before the command only.kater --warn-error compile
  • Options go anywhere. --json, --kater-root, --scope, --target, --profile and --profiles-dir may come before the command or after it. See Configuration for the profile and its targets. The log options come before it.
  • Repeat collection flags. Give one value per flag: --select a.sql --select b.sql. See Selecting models.
  • Set a scope once. kater scope use PATH saves the folder or model your commands work on.

Common options

Every command takes -h or --help, --kater-root ROOT, --scope PATH and --json, as the table above describes. Common options may come before the resource or after the final command.

Terminal window
# Put a common option before the resource
kater --json scope list
# Or after the final command
kater scope list --json
  • The command’s value wins. A command-specific value overrides a root value. Configured defaults follow the order in Configuration.
  • Relative paths. Scope paths and the paths a command takes resolve under --kater-root, or the attached session’s root. Otherwise they use the folder you run the command in. Auxiliary input files always resolve from the folder you run the command in.
  • Scope order. --scope, then a folder or file that --select names, then the saved default, then the current folder.