Command Line Interface

The Caliper SDK features a feature-rich command line interface that will serve as your main point of interaction with the product. Access it via command line script q2. By typing q2 and pressing the <Return> key, you can see all the operations, or “entrypoints”, available to you:

% q2
usage: q2 [-h] [-V]                                                                                                                                                       [4/1874]
          {add_nav_perms,add_to_nav,bounce_stack,check,create_coreflow,create_entrypoint,create_extension,db,test,generate_config,generate_hq_api,get_installed_forms,inspect,install
_completion,install,lint,remove_form,remove_from_nav,run_db_plan,run,run_sql,setup_db,setup,update,update_installed_form,upgrade}
          ...

positional arguments:
  {add_nav_perms,add_to_nav,bounce_stack,check,create_coreflow,create_entrypoint,create_extension,db,test,generate_config,generate_hq_api,get_installed_forms,inspect,install_completion,install,lint,remove_form,remove_from_nav,run_db_plan,run,run_sql,setup_db,setup,update,update_installed_form,upgrade}
    add_nav_perms       Set nav item permissions in Q2_UserPropertyData table
    add_to_nav          Add to Online environment's Navigation Menu
    bounce_stack        Restart the running stack (HQ, Ardent, Bridge, etc) (dev only)
    check               Analyze code against Q2 deployable standards
    create_coreflow     Create an extension to handle a new core process
    create_entrypoint   Create a custom entrypoint
    create_extension    Create a new extension skeleton
    db                  Database Operations
    test                Run unit tests on repo
    generate_config     Create an empty configuration file for a given
                        extension
    generate_hq_api     Generate easy to work with hq_api code from HQ_URL in
                        configuration.settings.py
    get_installed_forms
                        List all forms installed in the database
    inspect             View SDK version, HQ URL, and database parameters
    install_completion  Install command line completion hooks
    install             Install extension into Q2 database
    lint                Run linting on installed extensions
    remove_form         Remove extension as a form in Online environment
    remove_from_nav     Remove extension from Online environment's Navigation
                        Menu
    run_db_plan         Run an extension's DbPlan
    run                 Run the server
    run_sql             Run all SQL in install folders
    setup_db            Install Stored procs necessary to run the sdk
    setup               generate directories and files necessary to run sdk
    update              Update the changelog for an extension
    update_installed_form
                        Update the details of an installed form in the
                        database
    upgrade             Upgrade or rollback this project's q2-sdk or q2-cores
                        version

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Some of these have already been run to create your server (setup, setup_db). You’ve already used create_extension, run, install, and add_to_nav as part of the tutorial. Others you will likely use later, such as check to verify your code is valid for deployment, or upgrade to automatically download and install upgrades to the product.

You can see that each of them have a little help text associated with them. Some might also have additional parameters that can make using them more customizable. You can discover these by adding a -h at the end of the command. For instance, let’s try it with run:

$ q2 run -h
usage: q2 run [-h] [-c CONFIG_PATH] [-p PORT] [-l LOGGING_LEVEL]

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_PATH        Configuration settings file path
  -p PORT               Defaults to 1980
  -l LOGGING_LEVEL, --logging-level LOGGING_LEVEL
                        DEBUG, INFO, CRITICAL, ERROR

Nice! Looks like run has several options with which to control it’s behavior. By default, it runs the server on port 1980, but throwing a -p 1981 at the end would cause it to run on 1981 instead. A very useful parameter is the -l or --logging-level flag, with which you can make your script more or less verbose.

Add some -h options to a few of the other entrypoints to familiarize yourself with the toolbox. We are always improving and adding to this CLI, which we consider a core feature of the Caliper SDK. We hope you will be impressed by its feature set, power, and ease of use.