SQLcl `project` Cheat-Sheet

This is a good demo/overview of why project is here, you can skip to 9m 30s in. But why a cheat-sheet when it's already widely documented? I found help project from within SQLcl a bit slow to trawl through, and intrusive into your scroll history. Here's the 26ai online reference.

If you haven't heard of Liquibase, SQLcl has adopted it for managing database changes, and audits thereof. Type help lb from within SQLcl to understand more; project works in tandem with Liquibase (and git).

Sub-, and sub-sub-commands have no leading hyphen, -options do. Sub-commands in yellow; sub-sub-commands in blue. Some of these comments simply replicate the help info. Mandatory -options marked with red asterisk*.

Keyword	Short­ened	Comments
project	proj	It makes sense to establish a connection first
-verbose	-v	Available on all sub-commands
-debug	-de	Available on all sub-commands
init	in	Setup a new project in a git repo
-name*	-n*	Name your project (same as your git repo?)
-schemas*	-s*	Indicate which schema/s is/are relevant to this project; not technically a mandatory option, but you'll almost certainly need to set a schema
-directory	-d	Defaults to the current SQLcl working dir (cd to set, from within SQLcl)
-connection-name	-con	You may see a warning that the sqlConnection isn't set in your project, but so long as you are connected, ignore it
-makeroot	-mr	Create a root folder named after the project and store all files in this directory
export	ex	Export the schema and/or Apex app to a git repo; for an Apex export, see -objects.  Before your first export, you may want to amend the default export SQL formatting: you can't do this later as it will generate unwanted differences on a subsequent export.  See file: ./.dbtools/project.sqlformat.xml
-list	-l	List the objects that will be exported based on the given arguments
-objects	-o	Comma-separated objects to export; for an Apex app, state APEX.<app-id>; but note that apex is exported by default if relevant
-schemas	-s	Comma-separated schemas to export
-threads	-t	Defaults to 5 to help speed it up. Not sure why you might want to lower this, but I suppose hefty schemas may benefit from more threads.
stage	st	Create Liquibase changelogs & -sets for all source & custom files: stage the main export before staging DML via add-custom on top of it stage before the main export for any initial db setup, such as alter session etc you can always reorder the stages in the xml changelog before you move to release
-branch-name	-bn	Specify the branch name for comparison. If not provided, the value from the configuration file (git.defaultBranch) will be used, with "develop" as the default
add-custom	ac	Add a custom file to the stage/deployment
-file-name*	-fn*	Name to give it: you cannot import an existing file – you will need to copy/paste or cat-append maybe if you have a script already saved
-change-log	-ch	STAGE [default] | RELEASE | MAIN
release	re	Finalise the current release state so you can start a new pipeline
-version*	-ve*	Give this release a version no.
-include	-inc	Enables to release only (-inc) or all except (-exc) the specified changes. In case of multiple changes, specify the comma-delimited list with no spaces between change IDs.  Mutually exclusive
-exclude	-exc
gen-artifact	ga	Creates an artifact (zip/tgz bundle) that Liquibase uses to deploy your project via deploy later
-format	-fo	zip by default, or tgz
-version	-ve	Which version, by default the current
-force	-f	Overwrite an existing artifact
deploy	dp	Deploy an artifact created with gen-artifact above to a target database
-file*	-fs*	The filename to deploy, qualified from the current SQLcl working directory
-log-path	-ld	Override the default log directory
-defaults-file	-def	Specify the absolute path to the properties file that needs to be used instead of env/default.properties
config	cfg	View/manage project config properties; or edit ./.dbtools/project.config.json directly
-list*	-li*	Mandatory only with no set/delete sub-command; simply lists all the project options defined in ./.dbtools/project.config.json
-name	-n	Valid names only, or list all without this
set	s	Set a project parameter value (updates above file)
-name*	-n*	Valid names only
-value*	-va*	Valid values only
delete	d	Delete a parameter, -name* as before (removes from above file)
verify	v	Check for potential problems
-group	-gr	Execute a group of verify tests
-test	-se	Execute a Verification test
-list-groups	-lig	List all the registered verify service groups
-list-tests	-lit	If a group is supplied will list all the verify tests in that group, otherwise will list all verify tests registered
-compared-branch-name	-cbn	The name of the branch which the differences with the current branch will be checked for
verify-stage	st	Execute all the verify tests registered for the stage group
snapshot	ss	Execute all the verify tests registered for the snapshot group

If you found this cheat‑sheet useful, share it with a colleague or leave a comment with your favourite SQLcl trick.