SBT Command References

Every sbt command with a real example, the argument shapes, and the gotchas the --help text doesn't tell you.

Every command below includes a working example. All examples verified on sbt 1.0.13 (August 2026). Two rules that apply to everything:

  • Run sbt commands from inside your project folder (the one containing sbtconf.toml). sbt reads its config from the current directory; anywhere else you get a raw FileNotFoundError traceback. See Configuring Your Project.

  • There is no sbt --version. Check your installed version with pip show sbt.

⚠️ The built-in --help text is wrong or unhelpfully duplicated for several commands (ticketed as CRE-754). Trust this page over --help until that's fixed.

The core publisher loop

sbt build-app — upload your app code and register a version

sbt build-app --app-name snack_shop_insights --beta

  • Requires the --app-name flag. A positional name errors with "Got unexpected extra argument". (Yes, this is inconsistent with publish-app — CRE-769.)

  • The version number comes from your app config yaml. Bump version: there before building; build does not auto-increment anything.

  • --beta selects the beta (stored procedure) pipeline that all current production apps use.

  • Success looks like: App <name> Upload Successful - Version N followed by Uploading custom python modules...

sbt publish-app — make a built version available in the catalog

sbt publish-app snack_shop_insights 4 --beta

  • Positional NAME then VERSION — no flags for either (different shape than build-app). Omitting the version errors with "Missing argument 'VERSION'". Use the version number your build printed.

  • With --beta, the published version automatically becomes the app's default (is_default: True).

  • Publishing does NOT upgrade orgs that already installed the app. Each org upgrades manually from its Apps page — see Installing an App into an Organization.

sbt install-app — install into the org configured in sbtconf.toml

sbt install-app snack_shop_insights

  • Publisher shortcut for testing. The path customers (and admins) actually use is the browser: grant access > install > Set Data Access > source mappings. See Installing an App into an Organization.

sbt full-rebuild — build + publish + install in one command

sbt full-rebuild snack_shop_insights

Convenient once you're comfortable with the individual steps and their failure modes.

Inspecting

sbt lookup-app — list an app's versions with default/beta flags

sbt lookup-app snack_shop_insights

sbt read-app-spec — print the fully resolved spec from your LOCAL files

sbt read-app-spec snack_shop_insights

The single best "what am I actually about to ship?" tool: shows every model, parameter (including rls / is_bundled flags), resolved values queries, versions, and file paths — resolved from your local project, not from the cloud.

sbt ping-seek / sbt me — connectivity and identity checks

sbt ping-seek
sbt me

Local development and testing

sbt run-app / sbt run-model — run locally against your configured target

sbt run-app snack_shop_insights
sbt run-model region_share

Local outputs are written as <model_name>_test tables. A model that runs fine locally can still fail deployed — see Models > How models execute for the beta-path constraint on imports.

sbt validate-app / validate-model / validate-source — check configs without running

sbt validate-model region_share

sbt check-conn — verify the Snowflake connection in sbtconf.toml

sbt check-conn

Run this after any sbtconf.toml change and as the first debugging step for connection-looking errors.

Project setup

sbt init — scaffold a new project

sbt init

sbt init-config — interactive user config setup

sbt init-config

Creates/updates your sbtconf.toml. Double-check the org id it writes; see Configuring Your Project (sbtconf.toml).

Deprecated — do not use

  • sbt deploy-app

  • sbt deploy-model

Both are marked deprecated in the CLI. The platform deploys for you at build/publish time.

Related articles

⏭️ Next: Apps