Command Line Interface (CLI)

padams edited this page Oct 5, 2015 · 2 revisions

OWA has a command line interface (CLI) that allows administrators to perform certain commands from the server's shell instead of via the web.

A Note About Security

The CLI interface relies on the security of your filesystem for access control so be sure that only authorized system users have access to read, write and execute this file. See Required permissions for more info on how to secure your OWA installation.

Invoking the CLI

The CLI is invoked as a PHP5 script on the command line. Arguments are passed name/value pairs. The argument cmd must be present and contain a valid command name.

/path/to/php5 /path/to/owa/cli.php cmd=command_name arg1=bar

Commands

The CLI can be used to perform multiple tasks using the commands outlines below.

update

/path/to/php5 cli.php cmd=update

This command is used to apply the latest database schema updates to OWA when you move from one version of the code to another. The command offers fine grained control of which updates to apply using it's optional arguments.

Arguments

  • ''listpending''     ''optional'' - lists the updates that needot be applied but does ''not'' apply them.
  • ''apply''     ''optional'' - takes a concatenated string consisting of a module name and sequence number of the update that you want to apply (e.g. apply=base.006)
  • ''rollback''     ''optional'' - takes a concatenated string consisting of a module name and sequence number of the update that you want to rolback (e.g. rollback=base.006)

add-site

/path/to/php5 cli.php cmd=add-site

This command is used to add a new tracked site to OWA.

Arguments

  • ''domain''     '''required''' - the domain of the web site that you want to track. Best practice is to include the protocol (e.g. http://www.domain.com)
  • ''name''     ''optional'' - the name that you want to see the site listed as in the site roster.
  • ''description''     ''optional'' - a short description of the site.
  • ''site_family''     ''optional'' - the name of the site family/group that this site should be included in.

flush-cache

/path/to/php5 cli.php cmd=flush-cache

Flushes the persistent object cache. This is important to do after updates. Also more important to do this regularly if you are using OWA's file based object cache.

build

/path/to/php cli.php cmd=build

Builds the concatenated JavaScript packages that are used by the tracker and admin pages. You need to run this if you are modifying the libs that are included in the packages.

processEventQueue

/path/to/php5 cli.php cmd=processEventQueue

This command is used to process OWA's event queue. See Event processing for more info on why one would need to use this.

Arguments

  • ''source''     ''optional'' - the type of event queue to read from. Supported values are: ''file'' , ''database''
  • ''destination''     ''optional'' - the type of event queue to place any new events that are created as a result of processing the source queue. Supported values are: ''file'' , ''database''

The ''source'' and ''destination'' arguments are typically used in situations where there are multiple OWA servers logging events that need to process events from a local queue but deposit second order events in a shared queue on another machine. See Deployment and Event processing for more info.

install

/path/to/php5 cli.php cmd=install

This command will install OWA by applying the database schema, creating the admin user, and adding a tracked web site to the site roster. You must create OWA's configuration file manually before running this command. This command will create an admin user with the user name ''admin'' and a password that is equal to the database password that you define in your configuration file.

Arguments

  • ''domain''     '''Required'''. This is the domain of the first web site that you want to track.
  • ''email_address''     '''Required'''. This is the email address of the admin user. This is used in password recovery.

install-module

/path/to/php5 cli.php cmd=install-module

This command will install and active a module. If the module has database tables those will be created if they do not already exist.

Arguments

  • ''module''     '''Required'''. This is name of the module that you wish to install.

Registering New Commands

Modules can register their own CLI commands by using the registerCliCommand method. This method take a command name as well as a controller module/class string (e.g. base.foo). For example, to register new command add the follwing to your module's constructor:

$this->registerCliCommand('mycommand', 'base.mycontroller');