3. CLI Commands

3. CLI Commands
Prev	Chapter 9. Command Line Interface (CLI)	Next

To learn CLI commands type "help".

HammerDB CLI v6.0
Copyright © HammerDB Ltd hosted by tpc.org 2019-2026
Type "help" for a list of commands
Initialized Jobs on-disk database C:/Temp/hammer.DB using existing tables (69,632 bytes)
hammerdb>help
HammerDB v6.0 CLI Help Index

Type "help command" for more details on specific commands below

        buildschema
        checkschema
        ci
        cifix
        cilisten
        cipush
        cireset
        ciset
        cistatus
        cistop
        citmp
        clearscript
        custommonitor
        customscript
        datagenrun
        dbset
        deleteschema
        dgset
        diset
        distributescript
        giset
        jobs
        librarycheck
        loadscript
        metset
        metstart
        metstatus
        metstop
        pipe
        pipes
        print
        quit
        savescript
        steprun
        switchmode
        tcset
        tcstart
        tcstatus
        tcstop
        vucomplete
        vucreate
        vudestroy
        vurun
        vuset
        vustatus
        wsport
        wsstart
        wsstatus
        wsstop

hammerdb>

The commands have the following functionality.

Table 9.2. CLI commands

Command	Usage	Description
buildschema	Usage: buildschema	Runs the schema build for the database and benchmark selected with dbset and variables selected with diset. Equivalent to the Build command in the graphical interface. Note that the buildschema command will assume the "yes" reply to the Yes or no prompt to proceed with the schema build. This is to prevent the stalling of CLI scripts during builds.
checkschema	Usage: checkschema	Runs the schema consistency check for the database and benchmark selected with dbset and variables selected with diset. Equivalent to the Check command in the graphical interface.
deleteschema	Usage: deleteschema	Runs the schema delete for the database and benchmark selected with dbset and variables selected with diset. Equivalent to the Delete command in the graphical interface.
clearscript	Usage: clearscript	Clears the script. Equivalent to the "Clear the Screen" button in the graphical interface.
savescript	Usage: savescript	Save the script to a file. Equivalent to the "Save" button in the graphical interface.
customscript	Usage: customscript scriptname.tcl	Load an external script. Equivalent to the "Open Existing File" button in the graphical interface.
custommonitor	Usage: custommonitor test\|timed	Causes an additional Virtual User to be created when running vucreate. Used when loading a custom script.
datagenrun	Usage: datagenrun	Run Data Generation. Equivalent to the Generate option in the graphical interface.
dbset	Usage: dbset [db\|bm] value	Sets the database (db) or benchmark (bm). Equivalent to the Benchmark Menu in the graphical interface. Database value is set by the database prefix in the XML configuration.
dgset	Usage: dgset [vu\|ware\|directory]	Set the Datagen options. Equivalent to the Datagen Options dialog in the graphical interface.
diset	Usage: diset dict key value	Set the dictionary variables for the current database. Equivalent to the Schema Build and Driver Options windows in the graphical interface. Use "print dict" to see what these variables area and diset to change: Example: hammerdb>diset tpcc count_ware 10 Changed tpcc:count_ware from 1 to 10 for Oracle.
distributescript	Usage: distributescript	In Primary mode distributes the script loaded by Primary to the connected Replicas.
giset	Usage: giset dict key value	Set the dictionary variables for the generic settings. Use "print generic" to see what these variables are and giset to change Example: hammerdb>giset commandline keepalive_margin 60 Changed commandline:keepalive_margin from 10 to 60 for generic
jobs	Usage: jobs \| jobs jobid \| jobs jobid option	The jobs command records benchmark configuration, output, result, timing, transaction count, metrics and system data in the HammerDB jobs repository. Use jobs by itself to list jobs, jobs jobid to show job output, and jobs jobid with an option to show a specific part of a job. The command also supports output format, profile, diff, chart and save options. The job command remains an alias for jobs.
pipes	Usage: pipes \| pipes <pipeid>	Shows the CI pipeline summary table. With a pipeid, shows detailed pipeline output including status, timestamps, commit message, clone/build/install output, package command, config file, start command, CI dictionary and linked jobs.
pipe	Usage: pipe \| pipe <pipeid>	Alias for pipes.
ci	Usage: ci \| ci <pipeid>	Alias for pipes.
citmp	Usage: citmp	Shows the TMP directory and jobs database path used by CI.
cifix	Usage: cifix	Initialises or repairs the HammerDB CI environment, creates required directories under the configured CI base directory, downloads provider configuration files and validates the setup. TMP mismatch is reported as a warning only.
ciset	Usage: ciset top section key value	Updates a CI configuration entry and persists it in ci.db. For example, use ciset to update a provider repository URL or the common listener port.
cilisten	Usage: cilisten	Starts the CI GitHub webhook listener and job watcher on Linux/Unix. At startup cilisten runs cireset to clear stale blocking CI rows.
cistatus	Usage: cistatus	Shows whether the CI listener and watcher are running.
cistop	Usage: cistop	Stops the CI webhook listener and job watcher.
cireset	Usage: cireset	Marks incomplete CI pipeline rows as FAILED. This clears stale PENDING or RUNNING rows that would otherwise block a new CI pipeline, while preserving CI history.
cipush	Usage: cipush refname ?pipeline? ?workload? ?dbprefix? ?io_intensive?	Simulates a GitHub webhook push for a ref and inserts a CI pipeline request. The refname must be refs/tags/name, refs/heads/name or a commit SHA. Pipeline is commonly single, profile or compare. Workload is C or H. Dbprefix is maria, mysql or pg. The io_intensive flag is 0 or 1.
librarycheck	Usage: librarycheck	Attempts to load the vendor provided third-party library for all databases and reports whether the attempt was successful.
loadscript	Usage: loadscript	Load the script for the database and benchmark set with dbset and the dictionary variables set with diset. Use "print script" to see the script that is loaded. Equivalent to loading a Driver Script in the Script Editor window in the graphical interface.
metset	Usage: metset [agent_hostname\|agent_id]	Configure the CPU Metrics options. Equivalent to the Metrics Options window in the graphical interface.
metstart	Usage: metstart	Starts the CPU Metrics and agent if configured to the localhost.
metstatus	Usage: metstatus	Checks the status of the CPU Metrics.
metstop	Usage: metstop	Stops the CPU Metrics.
print	Usage: print [db\|bm\|dict\|generic\|script\|vuconf \|vucreated\|vustatus\|datagen]	prints the current configuration: db: database bm: benchmark dict: the dictionary for the current database ie all active variables generic: the dictionary for generic settings script: the loaded script vuconf: the virtual user configuration vucreated: the number of virtual users created vustatus: the status of the virtual users datagen : the configuration to build when datagen is run
quit	Usage: quit Shuts down the HammerDB CLI.	Calls the exit command and terminates the CLI interface
steprun	Usage: steprun	Automatically switches into Primary mode, creates and connects the multiple Replicas defined in config/steps.xml and starts the Primary and Replica Virtual Users at the defined intervals creating a step workload. Both Primary and Replicas will exit on completion.
switchmode	Usage: switchmode [mode] ?PrimaryID? ?PrimaryHostname?	Changes the remote mode to Primary, Replica or Local. When Master it will report an id and a hostname. Equivalent to the Mode option in the graphical interface. Mode to switch to must be one of Local, Primary or Replica. If Mode is Replica then the ID and Hostname of the Primary to connect to must be given.
tcset	Usage: tcset [refreshrate\|logtotemp\|unique\|timestamps]	Configure the transaction counter options. Equivalent to the Transaction Counter Options window in the graphical interface.
tcstart	Usage: tcstart	Starts the Transaction Counter.
tcstatus	Usage: tcstatus	Checks the status of the Transaction Counter.
tcstop	Usage: tcstop	Stops the Transaction Counter.
vucomplete	Usage: vucomplete	Returns "true" or "false" depending on whether all virtual users that started a workload have completed regardless of whether the status was "FINISH SUCCESS" or "FINISH FAILED".
vucreate	Usage: vucreate	Create the virtual users. Equivalent to the Virtual User Create option in the graphical interface. Use "print vucreated" to see the number created, vustatus to see the status and vucomplete to see whether all active virtual users have finished the workload. A script must be loaded before virtual users can be created.
vudestroy	Usage: vudestroy	Destroy the virtual users. Equivalent to the Destroy Virtual Users button in the graphical interface that replaces the Create Virtual Users button after virtual user creation.
vurun	Usage: vurun	Send the loaded script to the created virtual users for execution. Equivalent to the Run command in the graphical interface. In the CLI returns a jobid to access the workloads output and configuration.
vuset	Usage: vuset [vu\|delay\|repeat\|iterations\|showoutput \|logtotemp\|unique\|nobuff\|timestamps	Configure the virtual user options. Equivalent to the Virtual User Options window in the graphical interface. vuset expects an integer or the string "vcpu". Where "vcpu" is specified the vu value will be set to the number of logical CPUs detected on the system where HammerDB is running.
vustatus	Usage: vustatus	Show the status of virtual users. Status will be "WAIT IDLE" for virtual users that are created but not running a workload,"RUNNING" for virtual users that are running a workload, "FINISH SUCCESS" for virtual users that completed successfully or "FINISH FAILED" for virtual users that encountered an error.
wsport	Usage: wsport [ port number ]	Set or report the Web Service Port.
wsstart	Usage: wsstart	Start the Web Service.
wsstop	Usage: wsstop	Stops the Web Service.
wsstatus	Usage: wsstatus	Checks the status of the Web Service.

Note that the runtimer and waittocomplete parameters have been deprecated. For this reason an additional configuration parameter of keepalive_margin with a default value of 60 seconds in the generic.xml configuration file in the commandline section to modify the additional time that HammerDB will wait after completion before terminating the workload. This can be useful if for example gathering timing data for event driven scaling workloads with a large number of asynchronous clients.

3.1. CLI commands in Python

The HammerDB commands in Python mode are the same commands as the default Tcl mode, called as Python functions. Command arguments should be passed as Python strings or integers. Commands that take no arguments are called with empty parentheses, for example jobs(), pipes(), citmp(), cistatus() or quit().

Type help() to show the Python-mode command index. Type help('command') to show help for a specific command.

HammerDB CLI v6.0
Copyright © HammerDB Ltd hosted by tpc.org 2019-2026
Type "help()" for a list of commands
Initialized Jobs on-disk database C:/Temp/hammer.DB using existing tables (69,632 bytes)
hammerdb>help()
HammerDB v6.0 CLI Help Index

Type "help('command')" for more details on specific commands below

        buildschema
        checkschema
        ci
        cifix
        cilisten
        cipush
        cireset
        ciset
        cistatus
        cistop
        citmp
        clearscript
        custommonitor
        customscript
        datagenrun
        dbset
        deleteschema
        dgset
        diset
        distributescript
        giset
        jobs
        librarycheck
        loadscript
        metset
        metstart
        metstatus
        metstop
        pipe
        pipes
        print
        quit
        savescript
        steprun
        switchmode
        tcset
        tcstart
        tcstatus
        tcstop
        vucomplete
        vucreate
        vudestroy
        vurun
        vuset
        vustatus
        wsport
        wsstart
        wsstatus
        wsstop

The following example sets the number of virtual users and then prints the virtual user configuration from Python mode.

hammerdb>>>vuset('vu',10)
hammerdb>>>print('vuconf')
Virtual Users = 10
User Delay(ms) = 500
Repeat Delay(ms) = 500
Iterations = 1
Show Output = 1
Log Output = 0
Unique Log Name = 0
No Log Buffer = 0
Log Timestamps = 0

Jobs and pipeline output can also be queried from Python mode. The jobs command shows the current jobs repository, job result data, timing data, transaction count data, metrics, system information, generated charts and saved job report JSON. The examples below use JOBID as a placeholder for a HammerDB job id.

hammerdb>>>jobs()
hammerdb>>>jobs('format','text')
hammerdb>>>jobs('format','JSON')
hammerdb>>>jobs('result')
hammerdb>>>jobs('timestamp')
hammerdb>>>jobs('joblist')
hammerdb>>>jobs('JOBID')
hammerdb>>>jobs('JOBID','result')
hammerdb>>>jobs('JOBID','dict')
hammerdb>>>jobs('JOBID','timing')
hammerdb>>>jobs('JOBID','timing',2)
hammerdb>>>jobs('JOBID','tcount')
hammerdb>>>jobs('JOBID','metrics')
hammerdb>>>jobs('JOBID','system')
hammerdb>>>jobs('JOBID','getchart','result')
hammerdb>>>jobs('JOBID','getchart','timing')
hammerdb>>>jobs('JOBID','getchart','tcount')
hammerdb>>>jobs('JOBID','getchart','metrics')
hammerdb>>>jobs('JOBID','save')

Performance profile jobs can also be queried from Python mode. The profileid command shows or sets the active performance profile id, profile returns the jobs for a profile id, and diff compares two profile ids. The optional final diff argument enables weighted comparison when set to true.

hammerdb>>>jobs('profileid')
hammerdb>>>jobs('profileid',4)
hammerdb>>>jobs('profile',4)
hammerdb>>>jobs('diff',3,4,'false')
hammerdb>>>jobs('diff',3,4,'true')
hammerdb>>>jobs('4','getchart','profile')
hammerdb>>>jobs('3','getchart','diff:4')

The pipes, pipe and ci commands show CI pipeline status. Passing a pipeline id to pipes, pipe or ci displays the detailed pipeline output for that pipeline.

hammerdb>>>pipes()
hammerdb>>>pipes(12)
hammerdb>>>pipe(12)
hammerdb>>>ci(12)

The CI setup and listener commands are also available as Python functions. This allows a CI environment to be initialised, checked, started and stopped from an interactive Python CLI session.

hammerdb>>>cifix()
hammerdb>>>citmp()
hammerdb>>>ciset('MariaDB','build','repo_url','https://github.com/MariaDB/server.git')
hammerdb>>>cilisten()
hammerdb>>>cistatus()
hammerdb>>>cistop()
hammerdb>>>cireset()

The cipush command can be called from Python mode to simulate a GitHub webhook or manual pipeline trigger. The arguments are the reference name, pipeline mode, workload, database prefix and I/O-intensive flag.

hammerdb>>>cipush('refs/heads/11.8','single','C','maria',0)
hammerdb>>>cipush('refs/tags/mariadb-12.3.2','profile','C','maria',0)
hammerdb>>>cipush('refs/heads/11.8','compare','C','maria',0)
hammerdb>>>cipush('d33f879aec858063edd17aa2daa46db03abb2bae','profile','C','maria',0)

Prev	Up	Next
2. Start the CLI in Python	Home	4. Configure Schema Build