doc CLI reference (full-list)

Model Name

The -m/--model argument followed by the name of the model you want to document allows dbt-sugar to know which model you wish to document.

Syrup

The --syrup argument controls the configuration you wish dbt-sugar to use (see how to configure your sugar_config.yml). Normally, you will have specified a default syrup in your sugar_config.yaml but you may want to override it on-demand. To do so, you can pass --syrup maple_syrup on the dbt-sugar doc CLI call and dbt-sugar will use this config for that specific run instead of your default one. Note: if you have not set up a default syrup, dbt-sugar will error and demand that you define one or pass it via the CLI for each use (see sugar_config setup).

Target

dbt-sugar will read the dbt profile associated with the dbt project you want it to manage. It does so well because you declare the profile dbt should use when running models for you in your dbt_project.yml file (for more info check the dbt project documentation). You also generally declare a target in your dbt_profile.yml file (see dbt documentation). dbt-sugar figures it all out for you, how sweet is that?!

The --target argument allows you to override the default target that would normally be specified in dbt's profiles.yml for the profile associated with the dbt_project associated with the model you want to document. It is best practice to avoid using the `--target` argument unless you know what you are doing as it can lead to surprises (see Caveats & Gotchas). It is best to set a target: variable in your profiles.yml for each dbt project, you plan to have in dbt-sugar's scope (see dbt documentation).

Schema

Although dbt-sugar will figure out the database schema in which your model lives from the dbt_profiles.yml you may want to override it. If so, you can pass the --schema argument followed by the name of the schema you wish to target. It is best not to use this argument unless you have a good reason to as dbt-sugar will make a database call to see if the table you want to document exists in your database's metadata. If you point to a schema that does not contain that dbt model, dbt-sugar will error.

Preserve Yaml Order

The --preserve-yaml-order CLI flag disables dbt-sugar default behaviour alphabetical ordering sanitisation of your model descriptor files. This is particularly handy if you have comments in your YAML files that you want to keep.